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/commands/assetCommands.ts

@@ -111,6 +111,8 @@ export function buildAsset(type: AssetType, name: string, id = newId()): Asset {
       return { ...base, type: 'pattern', notes: [] };
     case 'song':
       return { ...base, type: 'song', tracks: defaultTracks(), items: [] };
+    case 'bus':
+      return { ...base, type: 'bus' };
     case 'particles':
       return { ...base, type: 'particles', graph: createEmptyGraph() };
   }

src/core/commands/projectCommands.ts

@@ -8,6 +8,7 @@ import {
 } from '../model/playSettings';
 import type { Project } from '../model/Project';
 import { clampSymbolScale } from '../model/symbolScale';
+import { clampMasterVolume } from '../model/master';
 import type { Command } from './Command';
 
 export class RenameProjectCommand implements Command {
@@ -126,3 +127,37 @@ export class SetGameLinkZoomCommand implements Command {
     project.gameLinkZoom = this.previous;
   }
 }
+
+/** The level of the master bus (#325), kept inside 0–1 like a loaded project's. */
+export class SetMasterVolumeCommand implements Command {
+  readonly label = 'Master volume';
+  private previous = 1;
+
+  constructor(private readonly volume: number) {}
+
+  execute(project: Project): void {
+    this.previous = project.masterVolume;
+    project.masterVolume = clampMasterVolume(this.volume);
+  }
+
+  undo(project: Project): void {
+    project.masterVolume = this.previous;
+  }
+}
+
+/** The sound FX of the master bus (#325), by id; '' for none. */
+export class SetMasterFxCommand implements Command {
+  readonly label = 'Master FX';
+  private previous = '';
+
+  constructor(private readonly fx: string) {}
+
+  execute(project: Project): void {
+    this.previous = project.masterFx;
+    project.masterFx = this.fx;
+  }
+
+  undo(project: Project): void {
+    project.masterFx = this.previous;
+  }
+}

src/core/graph/NodeContext.ts

@@ -240,7 +240,8 @@ export interface NodeContext {
    * the one case where the rule is in the way: the death sound of an object that destroys itself.
    * `fx` names a sound FX asset the voice is played through (#311); `''` plays it as it is.
    * `fxParams` are values for its parameters; one not given is the default the FX declares.
-   * `tempo` is what a Delay synced to beats counts by (#332).
+   * `tempo` is what a Delay synced to beats counts by (#332). `bus` is the bus it is heard on
+   * (#325): a bus asset or `MASTER_BUS`, `''` for the one the sound asset names.
    * Returns the number of the voice for `tuneSound`, or 0 where nothing is played.
    */
   playSound(
@@ -251,6 +252,7 @@ export interface NodeContext {
     fx: string,
     fxParams: FxParams,
     tempo: number,
+    bus: string,
   ): number;
   /**
    * Plays one note of an instrument asset (#331): `note` as MIDI counts it (60 is C4), struck with
@@ -258,6 +260,7 @@ export interface NodeContext {
    * held until it is stopped where that is 0. Owned like a `playSound` voice, `instrumentParams` are
    * values for the instrument's parameters, `tempo` as for `playSound`. `fx` sends the note through a
    * sound FX of its own (#346), `fxParams` with values for its parameters, apart from the instrument's.
+   * `bus` as for `playSound`, `''` for the one the instrument names.
    * Returns the number of the voice, 0 where nothing plays.
    */
   playNote(
@@ -271,12 +274,13 @@ export interface NodeContext {
     tempo: number,
     fx: string,
     fxParams: FxParams,
+    bus: string,
   ): number;
   /**
    * Plays a pattern asset through its instrument, at its own tempo, once or round and round, every
    * note at `volume`. Owned like a `playSound` voice. `fx` is a sound FX all of it goes through as
-   * one chain (#346), `fxParams` values for its parameters. Returns its number, for `stopVoice` and
-   * `tuneSound`; 0 where there is nothing to play.
+   * one chain (#346), `fxParams` values for its parameters, `bus` as for `playSound`. Returns its
+   * number, for `stopVoice` and `tuneSound`; 0 where there is nothing to play.
    */
   playPattern(
     patternId: string,
@@ -285,6 +289,7 @@ export interface NodeContext {
     detached: boolean,
     fx: string,
     fxParams: FxParams,
+    bus: string,
   ): number;
   /** Stops every playing of that pattern, `''` every pattern; `letRing` lets its notes fall away in their release. */
   stopPattern(patternId: string, letRing: boolean): void;
@@ -292,8 +297,8 @@ export interface NodeContext {
    * Plays a song asset (#336) at its tempo, its tracks as they are set: from its start, then round
    * the loop of its ruler with `loop`, else once to its end. `volume` (0 to 1) is the level of the
    * whole of it, rising there from silence over `fadeIn` seconds. Owned like a `playSound` voice.
-   * `fx` and `fxParams` as for `playPattern`, after its tracks. Returns its number; 0 where there is
-   * nothing to play.
+   * `fx`, `fxParams` and `bus` as for `playPattern`, after its tracks. Returns its number; 0 where
+   * there is nothing to play.
    */
   playSong(
     songId: string,
@@ -303,6 +308,7 @@ export interface NodeContext {
     detached: boolean,
     fx: string,
     fxParams: FxParams,
+    bus: string,
   ): number;
   /** Stops every playing of that song, `''` every song, falling silent over `fadeOut` seconds. */
   stopSong(songId: string, fadeOut: number): void;
@@ -329,6 +335,18 @@ export interface NodeContext {
    * quick glide.
    */
   tuneSound(voice: number, fxParams: FxParams, time: number, ease: EaseShare): void;
+  /**
+   * The same for the sound FX of a bus (#325): a bus asset or `MASTER_BUS`. A bus that is not there
+   * is not reached.
+   */
+  tuneBus(bus: string, fxParams: FxParams, time: number, ease: EaseShare): void;
+  /**
+   * Sets the volume of a bus (#325), `''` the master, over `time` seconds along `ease`. It holds
+   * for the rest of the run, over the volume of its asset and across scenes.
+   */
+  setBusVolume(bus: string, volume: number, time: number, ease: EaseShare): void;
+  /** The volume a bus is at, `''` the master: what a game set, else that of its asset; 0 for none. */
+  busVolume(bus: string): number;
   /**
    * Asks for another scene, by asset id. The swap happens once the frame is over – a graph must be
    * able to finish the flow it is in, and half a frame in the old world and half in the new one is

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,

src/core/model/Asset.ts

@@ -354,6 +354,14 @@ export interface SongAsset extends AssetBase {
   loop?: LoopRange;
 }
 
+/**
+ * Where sounds are mixed on their way out (#325): its volume, sound FX and the bus it goes into are
+ * properties (see `properties/buses.ts`). Sounds, instruments, patterns and songs name one.
+ */
+export interface BusAsset extends AssetBase {
+  type: 'bus';
+}
+
 /**
  * A tile a tilemap paints with: `pictures` names one block per animation step (a texture id for a
  * sheet that holds nothing else, a frame id for one block cut out of a sheet), and `props` say
@@ -610,6 +618,7 @@ export type Asset =
   | InstrumentAsset
   | PatternAsset
   | SongAsset
+  | BusAsset
   | ParticlesAsset;
 
 /** The assets whose `variables` are declared by the user – see `requireVariableOwner`. */

src/core/model/AssetTypes.ts

@@ -28,6 +28,7 @@ export const ASSET_TYPES = [
   'instrument',
   'pattern',
   'song',
+  'bus',
   'particles',
 ] as const;
 
@@ -63,6 +64,7 @@ export const ASSET_TYPE_LABELS: Record<AssetType, string> = {
   instrument: 'Instrument',
   pattern: 'Pattern',
   song: 'Song',
+  bus: 'Bus',
   particles: 'Particles',
 };
 
@@ -76,7 +78,8 @@ export const ASSET_TYPE_LABELS: Record<AssetType, string> = {
  * A struct is a shape that variables and fields take on (#253), nothing that exists on its own.
  * A shader function is part of other shaders (#303), worn by nothing itself. A sound FX is what a
  * sound is played through (#311), heard but never seen, an instrument what a note is played
- * with (#331), a pattern the notes it plays (#333) and a song what lays them out (#334).
+ * with (#331), a pattern the notes it plays (#333) and a song what lays them out (#334). A bus is
+ * where sounds are mixed on their way out (#325).
  */
 export type PlaceableAssetType = Exclude<
   AssetType,
@@ -97,6 +100,7 @@ export type PlaceableAssetType = Exclude<
   | 'instrument'
   | 'pattern'
   | 'song'
+  | 'bus'
   | 'variables'
   | 'struct'
 >;
@@ -119,6 +123,7 @@ const NOT_PLACEABLE: ReadonlySet<AssetType> = new Set([
   'instrument',
   'pattern',
   'song',
+  'bus',
   'variables',
   'struct',
 ]);

src/core/model/Project.ts

@@ -7,6 +7,7 @@ import {
   type SceneAsset,
 } from './Asset';
 import { DEFAULT_LAYER_NAME } from './collisionLayers';
+import { DEFAULT_MASTER_VOLUME } from './master';
 import {
   DEFAULT_GAME_LINK_ZOOM,
   DEFAULT_GAME_SCALE,
@@ -53,6 +54,12 @@ export interface Project {
    * written before there were any has just "Default", which every camera sees.
    */
   renderLayers: string[];
+  /**
+   * The level and the sound FX id of the master bus (#325), what every bus ends in. A project
+   * written before there was one has 1 and none, which is how it always sounded.
+   */
+  masterVolume: number;
+  masterFx: string;
   /**
    * Size of the scene view's symbol icons as a factor, 0.1 to 4 (see `symbolScale.ts`). A project
    * written before there was one reads as 1, the size the icons always had.
@@ -81,6 +88,8 @@ export function createEmptyProject(id: string, name: string): Project {
     plugins: [],
     collisionLayers: [DEFAULT_LAYER_NAME],
     renderLayers: [DEFAULT_LAYER_NAME],
+    masterVolume: DEFAULT_MASTER_VOLUME,
+    masterFx: '',
     symbolScale: DEFAULT_SYMBOL_SCALE,
     playFrom: DEFAULT_PLAY_FROM,
     whilePlaying: DEFAULT_WHILE_PLAYING,

src/core/model/master.ts

@@ -0,0 +1,22 @@
+/**
+ * The master bus of a project (#325): where every bus ends and every sound naming none is heard.
+ * Its level and its sound FX are project settings, not an asset, so there is always exactly one.
+ */
+export const DEFAULT_MASTER_VOLUME = 1;
+
+/** Keeps a level inside 0–1; anything that is not a finite number is the default. */
+export function clampMasterVolume(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return DEFAULT_MASTER_VOLUME;
+  return Math.min(1, Math.max(0, value));
+}
+
+/** The level as stored, read off untrusted JSON. A project written before there was one has 1. */
+export function masterVolumeOf(raw: unknown): number {
+  return clampMasterVolume((raw as { masterVolume?: unknown } | null)?.masterVolume);
+}
+
+/** The id of the sound FX of the master, '' for none. */
+export function masterFxOf(raw: unknown): string {
+  const fx = (raw as { masterFx?: unknown } | null)?.masterFx;
+  return typeof fx === 'string' ? fx : '';
+}

src/core/music/mixer.ts

@@ -0,0 +1,81 @@
+import { findAssetOf, type Project } from '../model/Project';
+import type { PropertyBag } from '../model/Properties';
+import { BUS_FX_KEY, busInto, busOf, busVolumeOf, MASTER_BUS } from '../properties/buses';
+import { coerceAs } from '../properties/kinds';
+import type { FxVoice } from '../soundfx/nodes';
+import { fxVoiceOf } from './needs';
+import { DEFAULT_TEMPO } from './time';
+
+/** What the sound library calls the master bus (#325); every other bus of the mix is `mix:<id>`. */
+export const MASTER_MIX = 'mix';
+
+/** One bus of the mix as the sound library sets it up: its level, its sound FX and where it goes. */
+export interface MixBus {
+  name: string;
+  volume: number;
+  /** The bus it goes into; null for the master, which is heard. */
+  into: string | null;
+  fx: FxVoice | null;
+}
+
+/** The name of a bus of the mix by the id of its asset; the master for '' and for `MASTER_BUS`. */
+export function mixBusName(busId: string): string {
+  return busId === '' || busId === MASTER_BUS ? MASTER_MIX : `mix:${busId}`;
+}
+
+/**
+ * The master and every bus of the project (#325), each into the bus it names – or the master, where
+ * that is missing or would make a loop. A sound FX that does not compile is none.
+ */
+export function mixOf(project: Project): MixBus[] {
+  const fxOf = (id: string) => fxVoiceOf(project, id, DEFAULT_TEMPO);
+  const buses = project.assets.flatMap((asset) =>
+    asset.type === 'bus'
+      ? [
+          {
+            name: mixBusName(asset.id),
+            volume: busVolumeOf(asset.props),
+            into: mixBusName(busInto(project, asset.id)),
+            fx: fxOf(coerceAs(asset.props[BUS_FX_KEY], 'asset', '')),
+          },
+        ]
+      : [],
+  );
+  return [
+    { name: MASTER_MIX, volume: project.masterVolume, into: null, fx: fxOf(project.masterFx) },
+    ...buses,
+  ];
+}
+
+/** Whether two mixes set the buses up the same: the same plan of a sound FX is the same object. */
+export function sameMix(a: readonly MixBus[], b: readonly MixBus[]): boolean {
+  return (
+    a.length === b.length &&
+    a.every((bus, i) => {
+      const other = b[i]!;
+      return (
+        bus.name === other.name &&
+        bus.volume === other.volume &&
+        bus.into === other.into &&
+        bus.fx?.plan === other.fx?.plan &&
+        bus.fx?.tempo === other.fx?.tempo
+      );
+    })
+  );
+}
+
+/**
+ * The bus of the mix something is heard on: the one a node picked, else the one its asset names.
+ * A pick naming no bus any more is the master, as a deleted bus would leave it.
+ */
+export function playedBus(project: Project, picked: string, assetProps: PropertyBag): string {
+  const id = picked !== '' ? picked : busOf(assetProps);
+  if (id === MASTER_BUS || id === '') return MASTER_MIX;
+  return findAssetOf(project, id, 'bus') ? mixBusName(id) : MASTER_MIX;
+}
+
+/** The bus of the mix a node reaches where an empty pick is the master: Set bus volume, Bus volume. */
+export function reachedBus(project: Project, picked: string): string | null {
+  if (picked === '' || picked === MASTER_BUS) return MASTER_MIX;
+  return findAssetOf(project, picked, 'bus') ? mixBusName(picked) : null;
+}

src/core/music/playbacks.ts

@@ -35,6 +35,8 @@ export interface SequencePlay {
   buses?: readonly BusLevel[];
   /** The sound FX the whole playing goes through (#346), after its tracks and before its level. */
   fx?: FxVoice;
+  /** The bus of the mix the whole playing is heard on (#325); the master where left out. */
+  bus?: string;
   /** Starts one note as the player was asked to, and gives back the number of its voice. */
   strike(note: ScheduledNote): number;
   strikeClip?(clip: ScheduledClip): number;

src/core/properties/PropertySchema.ts

@@ -139,13 +139,17 @@ import {
   SONG_TEMPO_KEY,
 } from '../music/song';
 import { DEFAULT_TEMPO, MAX_TEMPO, MIN_TEMPO } from '../music/time';
+import { BUS_FX_KEY, BUS_INTO_KEY, BUS_KEY, BUS_VOLUME_KEY } from './buses';
 import { Theme } from '../../ui';
 
 /**
  * What a kind's definition carries beyond key, label and default. `decimals` belongs only on
  * properties that are integral by meaning (counts, sizes in whole pixels), not on geometry: dragging
  * produces fractions, and the field rounds the value away rather than hiding it. Without
- * `assetTypes` an asset picker offers every placeable asset; `uploadedOnly` keeps drawn pictures out
+ * `assetTypes` an asset picker offers every placeable asset; `none` is what it calls an empty pick,
+ * `master` offers the master bus as a choice of its own, and `intoFor` names the bus the row is
+ * the Into of, which leaves out that bus and every one going into it when the picker opens (#325);
+ * `uploadedOnly` keeps drawn pictures out
  * of a texture picker (#186). `renderLayers` makes a layer row pick from the project's render layers
  * instead of its collision layers (#302), with "Inherit" as the first choice of a single layer.
  */
@@ -154,7 +158,7 @@ type Extras<K extends FlatKind> = K extends 'number'
   : K extends 'enum'
     ? { options: { value: string; label: string }[] }
     : K extends 'asset'
-      ? { assetTypes?: readonly AssetType[] }
+      ? { assetTypes?: readonly AssetType[]; none?: string; master?: boolean; intoFor?: string }
       : K extends 'texture'
         ? { uploadedOnly?: boolean }
         : K extends 'layer' | 'layers'
@@ -489,6 +493,16 @@ const SLICE_SCALE_ROW: PropertyDef = {
   step: 0.1,
 };
 
+/** The bus a sound, an instrument, a pattern or a song is heard on (#325). */
+const BUS_ROW: PropertyDef = {
+  key: BUS_KEY,
+  label: 'Bus',
+  kind: 'asset',
+  default: '',
+  assetTypes: ['bus'],
+  none: 'Master',
+};
+
 /** Position is deliberately absent: it belongs to scene objects, not to asset types. */
 const ASSET_SCHEMAS: Record<AssetType, PropertySchema> = {
   scene: [
@@ -719,11 +733,12 @@ const ASSET_SCHEMAS: Record<AssetType, PropertySchema> = {
         options: FADE_CURVES,
       },
     ]),
+    BUS_ROW,
   ],
   // The effects are the asset's graph (see SoundFxAsset), not a property.
   soundfx: [],
   // What a note sounds like is the asset's graph (see InstrumentAsset), not a property.
-  instrument: [],
+  instrument: [BUS_ROW],
   // The notes and the loop are intrinsic data on the asset (see PatternAsset). The meter and the
   // tempo are for drawing and hearing it on its own; a song plays it at its own tempo (#334).
   pattern: [
@@ -765,6 +780,7 @@ const ASSET_SCHEMAS: Record<AssetType, PropertySchema> = {
       max: MAX_TEMPO,
       step: 1,
     },
+    BUS_ROW,
   ],
   // The tracks, items and loop are intrinsic data on the asset (see SongAsset).
   song: [
@@ -795,6 +811,13 @@ const ASSET_SCHEMAS: Record<AssetType, PropertySchema> = {
       default: DEFAULT_SONG_GRID,
       options: SONG_GRID_OPTIONS,
     },
+    BUS_ROW,
+  ],
+  // Where sounds are mixed (#325): how loud, through which sound FX, and on into which bus.
+  bus: [
+    { key: BUS_VOLUME_KEY, label: 'Volume', kind: 'number', default: 1, min: 0, max: 1, step: 0.05 },
+    { key: BUS_FX_KEY, label: 'Sound FX', kind: 'asset', default: '', assetTypes: ['soundfx'] },
+    { ...BUS_ROW, key: BUS_INTO_KEY, label: 'Into' },
   ],
   // How many particles and for how long; what one of them does is the asset's graph, whose Property
   // nodes add their rows after these – see `schemaForBag`.
@@ -1143,6 +1166,11 @@ function schemaForBag(project: Project, asset: Asset, bag: PropertyBag): Propert
   // Nothing but declarations: the starting values live in `props` under the very same keys.
   if (asset.type === 'variables' || asset.type === 'struct') return asset.variables;
   if (asset.type === 'sprite') return [...FULL_SCHEMAS.sprite, ...shaderParamRows(project, shaderOf(bag))];
+  // A bus never goes into itself, nor into one that already goes into it.
+  if (asset.type === 'bus')
+    return FULL_SCHEMAS.bus.map((def) =>
+      def.key === BUS_INTO_KEY && def.kind === 'asset' ? { ...def, intoFor: asset.id } : def,
+    );
   // Unlike a sprite's shader, a source's graph is its own asset's, so no id has to be looked up.
   if (asset.type === 'particles')
     return sourceRows(

src/core/properties/assetRef.ts

@@ -1,8 +1,10 @@
 import type { Asset } from '../model/Asset';
 import { type AssetType, isPlaceableType } from '../model/AssetTypes';
 import { findAsset, type Project } from '../model/Project';
+import { MASTER_BUS } from './buses';
 
 export const NO_ASSET_LABEL = 'None';
+export const MASTER_LABEL = 'Master';
 
 /**
  * The asset's name, "None" for the empty id, `<id>?` when it no longer resolves – a dangling
@@ -10,6 +12,7 @@ export const NO_ASSET_LABEL = 'None';
  */
 export function assetRefLabel(project: Project | null, id: string): string {
   if (id === '') return NO_ASSET_LABEL;
+  if (id === MASTER_BUS) return MASTER_LABEL;
   return (project ? findAsset(project, id) : undefined)?.name ?? `${id}?`;
 }
 

src/core/properties/buses.ts

@@ -0,0 +1,59 @@
+import { findAssetOf, type Project } from '../model/Project';
+import type { PropertyBag } from '../model/Properties';
+import { coerceAs } from './kinds';
+
+/** The bus a sound, an instrument, a pattern or a song is heard on (#325); empty is the master. */
+export const BUS_KEY = 'bus';
+/** How loud a bus is, 0–1. */
+export const BUS_VOLUME_KEY = 'volume';
+/** The sound FX all of a bus goes through, before its volume. */
+export const BUS_FX_KEY = 'fx';
+/** The bus a bus goes into; empty is the master. */
+export const BUS_INTO_KEY = 'into';
+
+/**
+ * What a node picks to name the master where empty means something else: "from the asset" on a
+ * Play node, "no bus" on Set sound FX parameters. No asset id has a `#`.
+ */
+export const MASTER_BUS = '#master';
+
+export function busOf(bag: PropertyBag): string {
+  return coerceAs(bag[BUS_KEY], 'asset', '');
+}
+
+export function busVolumeOf(bag: PropertyBag): number {
+  return Math.max(0, Math.min(1, coerceAs(bag[BUS_VOLUME_KEY], 'number', 1)));
+}
+
+/** The bus a bus says it goes into, where that is a bus; '' for the master. */
+function namedInto(project: Project, busId: string): string {
+  const bus = findAssetOf(project, busId, 'bus');
+  const into = bus ? coerceAs(bus.props[BUS_INTO_KEY], 'asset', '') : '';
+  return into !== '' && findAssetOf(project, into, 'bus') ? into : '';
+}
+
+/** Whether following the buses on from `from` comes to `to`. */
+function reaches(project: Project, from: string, to: string): boolean {
+  const seen = new Set<string>();
+  for (let at = from; at !== '' && !seen.has(at); at = namedInto(project, at)) {
+    if (at === to) return true;
+    seen.add(at);
+  }
+  return false;
+}
+
+/**
+ * The bus a bus goes into, '' for the master. One that would come round to itself goes into the
+ * master instead, so however a project was written the buses never run in a loop.
+ */
+export function busInto(project: Project, busId: string): string {
+  const into = namedInto(project, busId);
+  return into !== '' && reaches(project, into, busId) ? '' : into;
+}
+
+/** The buses a bus cannot go into: itself and every one that already goes into it. */
+export function busesInto(project: Project, busId: string): string[] {
+  return project.assets
+    .filter((asset) => asset.type === 'bus' && reaches(project, asset.id, busId))
+    .map((asset) => asset.id);
+}

src/core/store/serialize.ts

@@ -57,6 +57,7 @@ import { renderLayersOf } from '../model/renderLayers';
 import { gameLinkZoomOf, gameScaleOf, playFromOf, whilePlayingOf } from '../model/playSettings';
 import { sceneVisibilityOf } from '../model/sceneVisibility';
 import { symbolScaleOf } from '../model/symbolScale';
+import { masterFxOf, masterVolumeOf } from '../model/master';
 import { decodeCells, encodeCells } from './tilemapCells';
 import { isAssetType } from '../model/AssetTypes';
 import { isFontFile } from '../model/font';
@@ -325,6 +326,8 @@ export function deserializeProject(raw: unknown, fallbackId = ''): Project {
     plugins: pluginsOf(r),
     collisionLayers: collisionLayersOf(r),
     renderLayers: renderLayersOf(r),
+    masterVolume: masterVolumeOf(r),
+    masterFx: masterFxOf(r),
     symbolScale: symbolScaleOf(r),
     playFrom: playFromOf(r),
     whilePlaying: whilePlayingOf(r),