Mix sounds through buses and a master (#325)

Until now every sound went straight to the speakers. There was no
point where all of them came together, so nothing could turn the
music down against the effects, and a compressor or a shared echo
over everything had nowhere to sit. The bus technique of #346 was
there already, only the end of the chain was missing.

- Bus asset (Audio): Volume, Sound FX and Into. Into is empty for
  the master and never offers the bus itself nor a bus that already
  goes into it. The list is worked out when the menu opens, so a
  change made meanwhile counts. A loop that is in a project anyway
  sends the buses on it into the master.
- The master is no asset. Its volume and sound FX are two new rows
  under Master in Project settings, one undo step each. A project
  written before has 1 and none, which is how it sounded.
- Sound, instrument, pattern and song have a row Bus, empty for the
  master. Play sound, Play note, Play pattern and Play song have an
  input bus: From the asset, Master or a bus. Inside a song or a
  pattern only the bus of the song or pattern counts.
- Set bus volume (bus, volume, time, easing) and Bus volume. An
  empty bus is the master. The volume set holds for the whole run,
  across scenes, over that of the asset. GameRun resets it at start
  and end. Set sound FX parameters without a voice now reaches the
  sound FX of the bus picked in its new bus input.
- SoundLibrary: the master is the bus "mix", each bus "mix:<id>".
  Every bus, the playing masters of #346 included, ends there, and
  only the master is heard. setMix sets them up once a context
  exists, so an editor nobody listened to opens no audio device. The
  same mix again changes nothing, which lets the editor hand it over
  on every change of the project.
- The tabs play as the game does: Sound, Sound FX, Instrument,
  Pattern and Song tab through the bus of their asset and the master.
- Pause game does nothing to the buses (the user's answer 4b). A
  game that wants quiet in its pause menu sets a bus volume itself.
- Streaming long music files is #349, split off as asked.

Finding on the way: the Into menu first worked from a list made when
the inspector row was built. After another bus was sent into the
open one, e2e 34 saw it still offered. It is now asked on open.

The SoundLibrary tests expected voices to end at the destination.
They now end in the master, which adds its input, level and pan to
every wiring and two gains to every list. Those expectations are
updated, nothing else in them changed.

Tests:
- Unit buses (new): 15 green. Ten counter-checks, each red on its
  own: loop check, bus picked, reset at run start, bus of Set sound
  FX parameters, master volume in the settings, and in SoundLibrary
  default into the master, voices into the master, run volume over
  the mix, no context before a play, a playing on its bus.
- Unit sound-library: 90 green (5 new). Node catalog: 416 green
  (9 new cases).
- e2e 34 (melektaus-atx): ALL PASSED, 75 checks (3 new). The voice
  of the Sound tab was heard on mix:<bus>, that bus into the other,
  that one at 0.5 into the master. Master volume 0.6 via the dialog,
  undo back to 1.
- Gate (melektaus-atx): CHECK EXIT 0, 262 files, 4072 tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/core/graph/nodes/action/PlayNote.ts

@@ -2,7 +2,7 @@ import { MIDDLE_C } from '../../../instrument/notes';
 import { heldTempo } from '../../../music/time';
 import type { NodeDef } from '../../NodeRegistry';
 import { asBoolean, asNumber, asString } from '../../values';
-import { exec, num, soundFxPort, withDefault } from '../shared';
+import { exec, num, playedBusPort, soundFxPort, withDefault } from '../shared';
 import { fxParamsOf, tempoPort } from './PlaySound';
 
 export const PlayNote: NodeDef = {
@@ -10,7 +10,7 @@ export const PlayNote: NodeDef = {
   label: 'Play note',
   category: 'action',
   description:
-    'Plays one note of an instrument asset. "note" is its number as MIDI counts it: 60 is C4, 61 C#4, 72 C5. "velocity" is how hard it is struck, 0 to 1 – it makes the note quieter and is handed to what the instrument does with it. "duration" is how many seconds until the note is released; at 0 it is held until a Stop sound ends it. A note belongs to this object like a sound and stops when the object is destroyed, unless "detached" is on. "params" takes values for the parameters of the instrument from an Instrument parameters node. "fx" sends the note through a sound FX on top of what the instrument does, "fx params" takes values for its parameters from a Sound FX parameters node – the two sets stay apart. "voice" is the number of this note, for Set sound FX parameters and Stop sound; 0 where the instrument plays nothing for it. "tempo" is what a Delay in the instrument synced to beats counts by, in quarter notes a minute.',
+    'Plays one note of an instrument asset. "note" is its number as MIDI counts it: 60 is C4, 61 C#4, 72 C5. "velocity" is how hard it is struck, 0 to 1 – it makes the note quieter and is handed to what the instrument does with it. "duration" is how many seconds until the note is released; at 0 it is held until a Stop sound ends it. A note belongs to this object like a sound and stops when the object is destroyed, unless "detached" is on. "params" takes values for the parameters of the instrument from an Instrument parameters node. "fx" sends the note through a sound FX on top of what the instrument does, "fx params" takes values for its parameters from a Sound FX parameters node – the two sets stay apart. "voice" is the number of this note, for Set sound FX parameters and Stop sound; 0 where the instrument plays nothing for it. "tempo" is what a Delay in the instrument synced to beats counts by, in quarter notes a minute. "bus" is the bus it is heard on; left empty, the one the instrument names.',
   inputs: [
     exec(),
     {
@@ -46,6 +46,7 @@ export const PlayNote: NodeDef = {
     tempoPort(),
     { ...soundFxPort(), key: 'soundFx' },
     { key: 'soundFxParams', label: 'fx params', type: 'fxparams' },
+    playedBusPort(),
   ],
   outputs: [exec(), num('voice')],
   params: [],
@@ -63,6 +64,7 @@ export const PlayNote: NodeDef = {
           heldTempo(asNumber(inputs.tempo)),
           asString(inputs.soundFx),
           fxParamsOf(inputs.soundFxParams),
+          asString(inputs.bus),
         )
       : 0;
     return { next: 'exec', outputs: { voice } };

src/core/graph/nodes/action/PlayPattern.ts

@@ -1,6 +1,6 @@
 import type { NodeDef, PortDef } from '../../NodeRegistry';
 import { asBoolean, asNumber, asString } from '../../values';
-import { exec, num, soundFxPort, withDefault } from '../shared';
+import { exec, num, playedBusPort, soundFxPort, withDefault } from '../shared';
 import { fxParamsOf } from './PlaySound';
 
 export const patternPort = (): PortDef => ({
@@ -23,7 +23,8 @@ export const PlayPattern: NodeDef = {
     '"detached" is on. "fx" sends all of it through one sound FX, its notes together: an LFO runs on ' +
     'across them, an echo repeats the whole. "fx params" takes values for its parameters from a Sound ' +
     'FX parameters node. "playback" is the number of this playing, for Stop pattern and for Set sound ' +
-    'FX parameters; 0 where the pattern has no instrument or no notes.',
+    'FX parameters; 0 where the pattern has no instrument or no notes. "bus" is the bus all of it is ' +
+    'heard on; left empty, the one the pattern names.',
   inputs: [
     exec(),
     patternPort(),
@@ -44,6 +45,7 @@ export const PlayPattern: NodeDef = {
     },
     soundFxPort(),
     { key: 'fxParams', label: 'fx params', type: 'fxparams' },
+    playedBusPort(),
   ],
   outputs: [exec(), num('playback')],
   params: [],
@@ -57,6 +59,7 @@ export const PlayPattern: NodeDef = {
           asBoolean(inputs.detached),
           asString(inputs.fx),
           fxParamsOf(inputs.fxParams),
+          asString(inputs.bus),
         )
       : 0;
     return { next: 'exec', outputs: { playback } };

src/core/graph/nodes/action/PlaySong.ts

@@ -1,6 +1,6 @@
 import type { NodeDef, PortDef } from '../../NodeRegistry';
 import { asBoolean, asNumber, asString } from '../../values';
-import { exec, num, soundFxPort, withDefault } from '../shared';
+import { exec, num, playedBusPort, soundFxPort, withDefault } from '../shared';
 import { fxParamsOf } from './PlaySound';
 
 export const songPort = (): PortDef => ({
@@ -24,7 +24,7 @@ export const PlaySong: NodeDef = {
     'is on. "fx" sends the whole song through one sound FX, after its tracks and before "volume"; ' +
     '"fx params" takes values for its parameters from a Sound FX parameters node. "playback" is the ' +
     'number of this playing, for Stop song and for Set sound FX parameters; 0 where the song has ' +
-    'nothing to play.',
+    'nothing to play. "bus" is the bus all of it is heard on; left empty, the one the song names.',
   inputs: [
     exec(),
     songPort(),
@@ -46,6 +46,7 @@ export const PlaySong: NodeDef = {
     },
     soundFxPort(),
     { key: 'fxParams', label: 'fx params', type: 'fxparams' },
+    playedBusPort(),
   ],
   outputs: [exec(), num('playback')],
   params: [],
@@ -60,6 +61,7 @@ export const PlaySong: NodeDef = {
           asBoolean(inputs.detached),
           asString(inputs.fx),
           fxParamsOf(inputs.fxParams),
+          asString(inputs.bus),
         )
       : 0;
     return { next: 'exec', outputs: { playback } };

src/core/graph/nodes/action/PlaySound.ts

@@ -3,7 +3,7 @@ import { DEFAULT_TEMPO, heldTempo, MAX_TEMPO, MIN_TEMPO } from '../../../music/t
 import type { FxParams } from '../../../soundfx/nodes';
 import type { NodeDef, PortDef } from '../../NodeRegistry';
 import { asBoolean, asNumber, asString, type Value } from '../../values';
-import { exec, num, soundFxPort, soundPort, withDefault } from '../shared';
+import { exec, num, playedBusPort, soundFxPort, soundPort, withDefault } from '../shared';
 
 /**
  * Three answers, not two: a checkbox cannot say "leave it to the asset", and without that a sound
@@ -66,7 +66,8 @@ export const PlaySound: NodeDef = {
     '"time" of Set sound FX parameters so a change spans the sound; 0 where nothing was played or ' +
     'the sound has not been loaded yet. A pitch never changes it. "tail" is that length and the ' +
     'echoes of its FX after it, as they are when it starts – how long until the voice is quiet. ' +
-    '"tempo" is what a Delay of its FX synced to beats counts by, in quarter notes a minute.',
+    '"tempo" is what a Delay of its FX synced to beats counts by, in quarter notes a minute. "bus" is ' +
+    'the bus it is heard on; left empty, the one the sound names.',
   inputs: [
     exec(),
     soundPort(),
@@ -76,6 +77,7 @@ export const PlaySound: NodeDef = {
     soundFxPort(),
     { key: 'fxParams', label: 'fx params', type: 'fxparams' },
     tempoPort(),
+    playedBusPort(),
   ],
   outputs: [exec(), num('voice'), num('length'), num('tail')],
   params: [],
@@ -90,6 +92,7 @@ export const PlaySound: NodeDef = {
           asString(inputs.fx),
           fxParamsOf(inputs.fxParams),
           heldTempo(asNumber(inputs.tempo)),
+          asString(inputs.bus),
         )
       : 0;
     const length = voice ? ctx.soundLength(sound) : 0;

src/core/graph/nodes/action/SetSoundFxParameters.ts

@@ -1,7 +1,7 @@
 import type { NodeDef } from '../../NodeRegistry';
-import { asNumber } from '../../values';
+import { asNumber, asString } from '../../values';
 import { curvesOf, easingOfParams, easingParams, idleEasing } from '../easing';
-import { exec, num } from '../shared';
+import { busPort, exec, num } from '../shared';
 import { fxParamsOf } from './PlaySound';
 
 import { easeShareOf } from '../../../model/animation';
@@ -23,26 +23,29 @@ export const SetSoundFxParameters: NodeDef = {
     'from another event. A parameter not given keeps its value, a voice that has ended is not ' +
     'reached. A pitch keeps the length of the sound here too, but is heard about 20 ms after it is set. ' +
     'time: seconds the values take to get there, along the chosen easing and on the clock of the ' +
-    'sound itself, so a sweep sounds the same every time; 0 is a quick glide.',
+    'sound itself, so a sweep sounds the same every time; 0 is a quick glide. Without a voice it changes ' +
+    'the sound FX of "bus" instead, the master or a bus asset, for everything heard on it.',
   inputs: [
     exec(),
     { ...num('voice'), inline: false },
     { key: 'fxParams', label: 'fx params', type: 'fxparams' },
     num('time'),
+    busPort('None', true),
   ],
   outputs: [exec()],
   params: easingParams(),
   idleParams: idleEasing,
   run: (ctx, inputs, params, _def, _entry, lookup) => {
     const voice = asNumber(inputs.voice);
+    const bus = asString(inputs.bus);
     const time = asNumber(inputs.time);
-    if (voice > 0)
-      ctx.tuneSound(
-        voice,
-        fxParamsOf(inputs.fxParams),
-        Number.isFinite(time) && time > 0 ? time : 0,
-        easeShareOf(easingOfParams(params), curvesOf(lookup)),
-      );
+    const glide = [
+      fxParamsOf(inputs.fxParams),
+      Number.isFinite(time) && time > 0 ? time : 0,
+      easeShareOf(easingOfParams(params), curvesOf(lookup)),
+    ] as const;
+    if (voice > 0) ctx.tuneSound(voice, ...glide);
+    else if (bus !== '') ctx.tuneBus(bus, ...glide);
     return { next: 'exec' };
   },
 };

src/core/graph/nodes/action/busNodes.ts

@@ -0,0 +1,46 @@
+import { easeShareOf } from '../../../model/animation';
+import type { NodeDef } from '../../NodeRegistry';
+import { asNumber, asString } from '../../values';
+import { curvesOf, easingOfParams, easingParams, idleEasing } from '../easing';
+import { busPort, exec, num, withDefault } from '../shared';
+
+/** The `bus` of Set bus volume and Bus volume: empty is the master. */
+const masterOrBus = () => busPort('Master', false);
+
+export const SetBusVolume: NodeDef = {
+  type: 'SetBusVolume',
+  label: 'Set bus volume',
+  category: 'action',
+  description:
+    'Sets how loud a bus is, 0 to 1, over "time" seconds along the chosen easing; 0 is a quick glide. ' +
+    'Left empty, "bus" is the master. The volume holds for the rest of the run, the next scene ' +
+    'included, over the one the bus asset has; Play starts with that of the asset again. To keep it ' +
+    'between runs, as an options menu does, keep it in the savegame and set it again at the start.',
+  inputs: [exec(), masterOrBus(), withDefault(num('volume'), 1), num('time')],
+  outputs: [exec()],
+  params: easingParams(),
+  idleParams: idleEasing,
+  run: (ctx, inputs, params, _def, _entry, lookup) => {
+    const time = asNumber(inputs.time);
+    ctx.setBusVolume(
+      asString(inputs.bus),
+      asNumber(inputs.volume),
+      Number.isFinite(time) && time > 0 ? time : 0,
+      easeShareOf(easingOfParams(params), curvesOf(lookup)),
+    );
+    return { next: 'exec' };
+  },
+};
+
+export const BusVolume: NodeDef = {
+  type: 'BusVolume',
+  label: 'Bus volume',
+  category: 'data',
+  description:
+    'How loud a bus is, 0 to 1: what Set bus volume set it to, else the volume of the bus asset. ' +
+    'Left empty, "bus" is the master. 0 for a bus that does not exist.',
+  inputs: [masterOrBus()],
+  outputs: [num('volume')],
+  params: [],
+  read: (ctx, _params, input) => ({ volume: ctx.busVolume(asString(input('bus'))) }),
+};

src/core/graph/nodes/index.ts

@@ -24,6 +24,7 @@ import { RaycastAll } from './action/RaycastAll';
 import { RestartGame } from './action/RestartGame';
 import { SetPosition } from './action/SetPosition';
 import { SetSoundFxParameters } from './action/SetSoundFxParameters';
+import { BusVolume, SetBusVolume } from './action/busNodes';
 import { PlayNote } from './action/PlayNote';
 import { PlayPattern } from './action/PlayPattern';
 import { StopPattern } from './action/StopPattern';
@@ -316,6 +317,8 @@ export const BUILT_IN_NODES: readonly NodeDef[] = [
   StopPattern,
   PlaySong,
   StopSong,
+  SetBusVolume,
+  BusVolume,
   LoadScene,
   Log,
   StopGame,

src/core/graph/nodes/shared.ts

@@ -102,6 +102,20 @@ export const soundFxPort = (): PortDef => ({
   field: { key: 'fx', label: 'FX', kind: 'asset', default: '', assetTypes: ['soundfx'] },
 });
 
+/**
+ * The `bus` input of a node that plays or reaches a bus (#325). `none` is what an empty pick means
+ * there; `master` offers the master as a pick of its own where empty means something else.
+ */
+export const busPort = (none: string, master: boolean): PortDef => ({
+  key: 'bus',
+  label: 'bus',
+  type: 'string',
+  field: { key: 'bus', label: 'Bus', kind: 'asset', default: '', assetTypes: ['bus'], none, master },
+});
+
+/** The `bus` input of a Play node: empty is the bus its asset names. */
+export const playedBusPort = (): PortDef => busPort('From the asset', true);
+
 export function binaryMath(type: string, description: string, fn: (a: number, b: number) => number): NodeDef {
   return {
     type,