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>

tests/core/buses.test.ts

@@ -0,0 +1,289 @@
+/**
+ * Master and buses (#325): which bus a bus goes into, what the sound library is set up with, and
+ * which bus a sound, a note, a pattern or a song is heard on.
+ */
+import { describe, expect, it } from 'vitest';
+import {
+  buildAsset,
+  CreateAssetCommand,
+  CreateSoundCommand,
+  SetAssetPropertyCommand,
+} from '../../src/core/commands/assetCommands';
+import { SetMasterFxCommand, SetMasterVolumeCommand } from '../../src/core/commands/projectCommands';
+import type { BehaviorAsset, SoundFxAsset } from '../../src/core/model/Asset';
+import { isPlaceableType } from '../../src/core/model/AssetTypes';
+import {
+  MASTER_MIX,
+  type MixBus,
+  mixBusName,
+  mixOf,
+  playedBus,
+  reachedBus,
+  sameMix,
+} from '../../src/core/music/mixer';
+import { BUS_INTO_KEY, BUS_KEY, busesInto, busInto, MASTER_BUS } from '../../src/core/properties/buses';
+import { schemaForAsset } from '../../src/core/properties/PropertySchema';
+import type { FxParams, FxVoice } from '../../src/core/soundfx/nodes';
+import { GameRun } from '../../src/runtime/GameRun';
+import { SILENT_AUDIO } from '../../src/runtime/systems/Audio';
+import { Input } from '../../src/runtime/systems/Input';
+import {
+  graphEditor,
+  makeBehavior,
+  makeProject,
+  makeSpriteScene,
+  place,
+  roundTrip,
+  startWorld,
+} from '../helpers';
+
+const FILE = `${'a1'.repeat(32)}.wav`;
+
+function withBuses(...names: string[]) {
+  const f = makeProject();
+  const ids = names.map((name) => {
+    const command = new CreateAssetCommand('bus', name);
+    f.stack.execute(command);
+    return command.asset.id;
+  });
+  const into = (bus: string, target: string) =>
+    f.stack.execute(new SetAssetPropertyCommand(bus, BUS_INTO_KEY, target));
+  return { ...f, ids, into };
+}
+
+/** A sound FX that compiles: Input, a Gain, Output. */
+function workingFx(f: ReturnType<typeof makeProject>): string {
+  const command = new CreateAssetCommand('soundfx', 'Squash');
+  f.stack.execute(command);
+  const edit = graphEditor(f, command.asset as SoundFxAsset as unknown as BehaviorAsset);
+  const input = edit.addNode('SoundFxInput');
+  const gain = edit.addNode('SoundFxGain', { gain: -6 });
+  const output = edit.addNode('SoundFxOutput');
+  edit.connect(input, 'out', gain, 'in');
+  edit.connect(gain, 'out', output, 'in');
+  return command.asset.id;
+}
+
+describe('the bus asset (#325)', () => {
+  it('is not placeable and starts at full volume, without a sound FX, into the master', () => {
+    expect(isPlaceableType('bus')).toBe(false);
+    const f = withBuses('Music');
+    const bus = f.project.assets[0]!;
+    expect(buildAsset('bus', 'SFX')).toMatchObject({ type: 'bus', props: { volume: 1, fx: '', into: '' } });
+    expect(schemaForAsset(f.project, bus).map((def) => def.key)).toEqual(['volume', 'fx', 'into']);
+    expect(roundTrip(f.project)).toEqual(f.project);
+  });
+
+  it('names the master as the empty pick of Into and of the Bus of a sound, an instrument, a pattern and a song', () => {
+    const f = withBuses('Music');
+    const into = schemaForAsset(f.project, f.project.assets[0]!).find((def) => def.key === BUS_INTO_KEY);
+    expect(into).toMatchObject({ kind: 'asset', assetTypes: ['bus'], none: 'Master' });
+    for (const type of ['sound', 'instrument', 'pattern', 'song'] as const) {
+      const command = new CreateAssetCommand(type, type);
+      f.stack.execute(command);
+      expect(schemaForAsset(f.project, command.asset).find((def) => def.key === BUS_KEY)).toMatchObject({
+        none: 'Master',
+        assetTypes: ['bus'],
+      });
+    }
+  });
+
+  it('offers as Into neither itself nor a bus that already goes into it', () => {
+    const f = withBuses('Master music', 'Music', 'Drums', 'SFX');
+    const [top, music, drums, sfx] = f.ids as [string, string, string, string];
+    f.into(music, top);
+    f.into(drums, music);
+    const rows = schemaForAsset(
+      f.project,
+      f.project.assets.find((a) => a.id === top)!,
+    );
+    expect(rows.find((d) => d.key === BUS_INTO_KEY)).toMatchObject({ intoFor: top });
+    expect(busesInto(f.project, top)).toEqual([top, music, drums]);
+    expect(busesInto(f.project, drums)).toEqual([drums]);
+    expect(busesInto(f.project, sfx)).toEqual([sfx]);
+  });
+
+  it('sends a bus that would come round to itself into the master, whatever the file says', () => {
+    const f = withBuses('A', 'B', 'C');
+    const [a, b, c] = f.ids as [string, string, string];
+    f.into(a, b);
+    f.into(b, c);
+    f.into(c, b);
+    // B and C go round each other: both go into the master. A goes into B, which is no loop.
+    expect([busInto(f.project, a), busInto(f.project, b), busInto(f.project, c)]).toEqual([b, '', '']);
+    f.into(a, a);
+    expect(busInto(f.project, a)).toBe('');
+    f.into(a, 'gone');
+    expect(busInto(f.project, a)).toBe('');
+  });
+});
+
+describe('the master (#325)', () => {
+  it('is a project setting at full volume without a sound FX, kept through a round trip', () => {
+    const f = makeProject();
+    expect([f.project.masterVolume, f.project.masterFx]).toEqual([1, '']);
+    f.stack.execute(new SetMasterVolumeCommand(2));
+    f.stack.execute(new SetMasterFxCommand('fx-1'));
+    expect([f.project.masterVolume, f.project.masterFx]).toEqual([1, 'fx-1']);
+    f.stack.execute(new SetMasterVolumeCommand(0.4));
+    expect(roundTrip(f.project)).toMatchObject({ masterVolume: 0.4, masterFx: 'fx-1' });
+    f.stack.undo();
+    f.stack.undo();
+    expect([f.project.masterVolume, f.project.masterFx]).toEqual([1, '']);
+  });
+
+  it('reads as full volume without a sound FX from a project written before there was one', () => {
+    const f = makeProject();
+    const written = roundTrip(f.project) as unknown as Record<string, unknown>;
+    delete written.masterVolume;
+    delete written.masterFx;
+    expect(roundTrip(written as never)).toMatchObject({ masterVolume: 1, masterFx: '' });
+  });
+});
+
+describe('the mix (#325)', () => {
+  it('is the master first, then every bus into the one it names, with its volume and its sound FX', () => {
+    const f = withBuses('Music', 'Drums');
+    const [music, drums] = f.ids as [string, string];
+    const fx = workingFx(f);
+    f.into(drums, music);
+    f.stack.execute(new SetAssetPropertyCommand(drums, 'volume', 0.5));
+    f.stack.execute(new SetAssetPropertyCommand(music, 'fx', fx));
+    f.stack.execute(new SetMasterVolumeCommand(0.8));
+    const mix = mixOf(f.project);
+    expect(mix.map(({ name, volume, into }) => ({ name, volume, into }))).toEqual([
+      { name: MASTER_MIX, volume: 0.8, into: null },
+      { name: `mix:${music}`, volume: 1, into: MASTER_MIX },
+      { name: `mix:${drums}`, volume: 0.5, into: `mix:${music}` },
+    ]);
+    expect(mix.map((bus) => bus.fx !== null)).toEqual([false, true, false]);
+  });
+
+  it('is the same mix again while nothing of it changed, another once a volume does', () => {
+    const f = withBuses('Music');
+    const before = mixOf(f.project);
+    expect(sameMix(before, mixOf(f.project))).toBe(true);
+    f.stack.execute(new SetAssetPropertyCommand(f.ids[0]!, 'volume', 0.2));
+    expect(sameMix(before, mixOf(f.project))).toBe(false);
+  });
+
+  it('plays on the bus a node picks, else the one its asset names, else the master', () => {
+    const f = withBuses('Music', 'SFX');
+    const [music, sfx] = f.ids as [string, string];
+    expect(playedBus(f.project, '', { bus: music })).toBe(`mix:${music}`);
+    expect(playedBus(f.project, sfx, { bus: music })).toBe(`mix:${sfx}`);
+    expect(playedBus(f.project, MASTER_BUS, { bus: music })).toBe(MASTER_MIX);
+    expect(playedBus(f.project, '', {})).toBe(MASTER_MIX);
+    // A bus that was deleted leaves it on the master.
+    expect(playedBus(f.project, '', { bus: 'gone' })).toBe(MASTER_MIX);
+  });
+
+  it('reaches the master for an empty pick, and no bus for one that is not there', () => {
+    const f = withBuses('Music');
+    expect(reachedBus(f.project, '')).toBe(MASTER_MIX);
+    expect(reachedBus(f.project, MASTER_BUS)).toBe(MASTER_MIX);
+    expect(reachedBus(f.project, f.ids[0]!)).toBe(mixBusName(f.ids[0]!));
+    expect(reachedBus(f.project, 'gone')).toBeNull();
+  });
+});
+
+/** What a run asked of the buses, beside the voices it played and on which bus. */
+function busSink() {
+  const sink = {
+    ...SILENT_AUDIO,
+    calls: [] as string[],
+    play: (file: string, _volume: number, _loop: boolean, _owner: string, _fx?: FxVoice, bus = '') => {
+      sink.calls.push(`play ${file} on ${bus}`);
+      return 1;
+    },
+    setMix: (buses: readonly MixBus[]) =>
+      void sink.calls.push(`mix ${buses.map((bus) => bus.name).join(' ')}`),
+    resetMix: () => void sink.calls.push('reset'),
+    setMixVolume: (bus: string, volume: number, time = 0) =>
+      void sink.calls.push(`volume ${bus} ${volume} ${time}`),
+    mixVolume: (bus: string) => (bus === MASTER_MIX ? 0.7 : 0.2),
+    tuneMix: (bus: string, params: FxParams) => void sink.calls.push(`tune ${bus} ${JSON.stringify(params)}`),
+  };
+  return sink;
+}
+
+/** A scene whose behavior runs `type` on its first frame, its result in a variable "Got". */
+function runOnStart(type: string, params: Record<string, string | number | boolean>, f = makeSpriteScene()) {
+  const behavior = makeBehavior(f, 'Logic', ['Got']);
+  place(f, behavior.id, { x: 0, y: 0 });
+  const edit = graphEditor(f, behavior);
+  const start = edit.addNode('OnStart');
+  const node = edit.addNode(type, params);
+  edit.connect(start, 'exec', node, 'exec');
+  return { ...f, behavior, edit, node };
+}
+
+describe('buses in a running game (#325)', () => {
+  it('plays a sound on the bus its asset names, or on the one Play sound picks', () => {
+    const f = makeSpriteScene();
+    const bus = new CreateAssetCommand('bus', 'SFX');
+    const sound = new CreateSoundCommand('Jump', FILE);
+    f.stack.execute(bus);
+    f.stack.execute(sound);
+    f.stack.execute(new SetAssetPropertyCommand(sound.asset.id, BUS_KEY, bus.asset.id));
+    runOnStart('PlaySound', { sound: sound.asset.id, volume: 1 }, f);
+    const asset = busSink();
+    startWorld(f, { behaviors: true, audio: asset }).frame();
+    expect(asset.calls).toEqual([`play ${FILE} on mix:${bus.asset.id}`]);
+
+    const picked = makeSpriteScene();
+    const pickedSound = new CreateSoundCommand('Jump', FILE);
+    picked.stack.execute(pickedSound);
+    runOnStart('PlaySound', { sound: pickedSound.asset.id, volume: 1, bus: MASTER_BUS }, picked);
+    const master = busSink();
+    startWorld(picked, { behaviors: true, audio: master }).frame();
+    expect(master.calls).toEqual([`play ${FILE} on ${MASTER_MIX}`]);
+  });
+
+  it('sets the volume of the master for an empty pick, and of the bus picked, over its time', () => {
+    const f = runOnStart('SetBusVolume', { bus: '', volume: 0.25, time: 2 });
+    const sink = busSink();
+    startWorld(f, { behaviors: true, audio: sink }).frame();
+    expect(sink.calls).toEqual([`volume ${MASTER_MIX} 0.25 2`]);
+
+    const gone = runOnStart('SetBusVolume', { bus: 'gone', volume: 0.25 });
+    const none = busSink();
+    startWorld(gone, { behaviors: true, audio: none }).frame();
+    expect(none.calls).toEqual([]);
+  });
+
+  it('changes the sound FX of a bus with Set sound FX parameters and no voice', () => {
+    const f = runOnStart('SetSoundFxParameters', { voice: 0, bus: MASTER_BUS });
+    const sink = busSink();
+    startWorld(f, { behaviors: true, audio: sink }).frame();
+    expect(sink.calls).toEqual([`tune ${MASTER_MIX} {}`]);
+  });
+
+  it('reads the volume a bus is at, the master for an empty pick and 0 for a bus that is not there', () => {
+    const f = runOnStart('Log', {});
+    const read = f.edit.addNode('BusVolume', { bus: '' });
+    f.edit.connect(read, 'volume', f.node, 'message');
+    const gone = f.edit.addNode('BusVolume', { bus: 'gone' });
+    const second = f.edit.addNode('Log');
+    f.edit.connect(f.node, 'exec', second, 'exec');
+    f.edit.connect(gone, 'volume', second, 'message');
+    const started = startWorld(f, { behaviors: true, audio: busSink() });
+    started.frame();
+    expect(started.world.log).toEqual(['0.7', '0']);
+  });
+
+  it('starts every run with the buses as their assets have them, and ends it so', () => {
+    const f = makeSpriteScene();
+    f.stack.execute(new CreateAssetCommand('bus', 'Music'));
+    const sink = busSink();
+    const run = GameRun.start(f.project, f.sceneId, new Input(), {
+      audio: sink,
+      physics: undefined as never,
+      clock: { scale: 1 },
+      saves: { read: () => ({}), write: () => {} },
+    });
+    expect(sink.calls).toEqual(['reset', `mix ${MASTER_MIX} mix:${f.project.assets.at(-1)!.id}`]);
+    run.end();
+    expect(sink.calls.at(-1)).toBe('reset');
+  });
+});

tests/core/holders.test.ts

@@ -153,6 +153,8 @@ describe('CommandStack', () => {
       plugins: [],
       collisionLayers: ['Default'],
       renderLayers: ['Default'],
+      masterVolume: 1,
+      masterFx: '',
       symbolScale: 1,
       playFrom: 'start' as const,
       whilePlaying: 'live' as const,

tests/core/keep-on-scene-load.test.ts

@@ -67,6 +67,11 @@ function start(f: Fixture, audio?: AudioSink) {
     tail: () => 0,
     stopVoice: () => {},
     stopOwner: (owner: string) => stoppedOwners.push(owner),
+    setMix: () => {},
+    setMixVolume: () => {},
+    mixVolume: () => 1,
+    resetMix: () => {},
+    tuneMix: () => {},
   };
   const run = GameRun.start(f.project, f.sceneId, new Input(), {
     audio: sink,

tests/core/node-catalog.test.ts

@@ -18,6 +18,7 @@ import {
   worldPositionOf,
 } from '../../src/core/graph';
 import type { PropertyBag } from '../../src/core/model/Properties';
+import { MASTER_BUS } from '../../src/core/properties/buses';
 import { fakeContext, type FakeContext, fakeEntity, fakeHandle, NO_POINTER, runDef } from '../helpers';
 
 interface Case {
@@ -2033,6 +2034,12 @@ const CASES: Record<string, Case[]> = {
       next: 'exec',
       after: (ctx) => expect(ctx.played[0]?.fxParams).toEqual({ depth: -12 }),
     },
+    {
+      name: 'hands on the bus it picks, the master among them (#325)',
+      inputs: { sound: 'snd-1', volume: 1, loop: '', bus: MASTER_BUS },
+      next: 'exec',
+      after: (ctx) => expect(ctx.played[0]?.bus).toBe(MASTER_BUS),
+    },
   ],
   PlayNote: [
     {
@@ -2087,6 +2094,12 @@ const CASES: Record<string, Case[]> = {
       next: 'exec',
       after: (ctx) => expect(ctx.notes[0]?.tempo).toBe(90),
     },
+    {
+      name: 'hands on the bus it picks (#325)',
+      inputs: { instrument: 'ins-1', note: 60, bus: 'bus-1' },
+      next: 'exec',
+      after: (ctx) => expect(ctx.notes[0]?.bus).toBe('bus-1'),
+    },
   ],
   InstrumentParameterValues: [
     {
@@ -2098,6 +2111,12 @@ const CASES: Record<string, Case[]> = {
     { name: 'with none picked the bundle is empty', outputs: { params: {} } },
   ],
   PlayPattern: [
+    {
+      name: 'hands on the bus it picks (#325)',
+      inputs: { pattern: 'pat-1', bus: 'bus-1' },
+      next: 'exec',
+      after: (ctx) => expect(ctx.patterns[0]?.bus).toBe('bus-1'),
+    },
     {
       name: 'no pattern is a no-op that still continues the flow',
       inputs: { pattern: '' },
@@ -2155,6 +2174,12 @@ const CASES: Record<string, Case[]> = {
     },
   ],
   PlaySong: [
+    {
+      name: 'hands on the bus it picks (#325)',
+      inputs: { song: 'song-1', bus: 'bus-1' },
+      next: 'exec',
+      after: (ctx) => expect(ctx.songs[0]?.bus).toBe('bus-1'),
+    },
     {
       name: 'no song is a no-op that still continues the flow',
       inputs: { song: '' },
@@ -2270,6 +2295,24 @@ const CASES: Record<string, Case[]> = {
     },
   ],
   SetSoundFxParameters: [
+    {
+      name: 'without a voice reaches the bus it picks instead (#325)',
+      inputs: { voice: 0, bus: MASTER_BUS, fxParams: { depth: 3 }, time: 2 },
+      next: 'exec',
+      after: (ctx) => {
+        expect(ctx.tuned).toEqual([]);
+        expect(ctx.buses).toEqual([{ bus: MASTER_BUS, fxParams: { depth: 3 }, time: 2, ease: 'linear' }]);
+      },
+    },
+    {
+      name: 'a voice wins over a bus, and with neither nothing is reached',
+      inputs: { voice: 4, bus: 'bus-1', fxParams: { depth: 3 } },
+      next: 'exec',
+      after: (ctx) => {
+        expect(ctx.tuned.map((t) => t.voice)).toEqual([4]);
+        expect(ctx.buses).toEqual([]);
+      },
+    },
     {
       name: 'hands the numbers of the bundle to the voice it is given',
       inputs: { voice: 4, fxParams: { depth: 3, label: 'x' } },
@@ -2395,6 +2438,29 @@ const CASES: Record<string, Case[]> = {
       outputs: { scale: 0.25 },
     },
   ],
+  SetBusVolume: [
+    {
+      name: 'sets the volume of the bus it picks over its time, empty being the master (#325)',
+      inputs: { bus: '', volume: 0.3, time: 1.5 },
+      next: 'exec',
+      after: (ctx) => expect(ctx.buses).toEqual([{ bus: '', volume: 0.3, time: 1.5, ease: 'linear' }]),
+    },
+    {
+      name: 'a time below 0 is a quick glide, along the easing it is given',
+      inputs: { bus: 'bus-1', volume: 0, time: -1 },
+      params: { ease: 'step' },
+      next: 'exec',
+      after: (ctx) => expect(ctx.buses).toEqual([{ bus: 'bus-1', volume: 0, time: 0, ease: 'step' }]),
+    },
+  ],
+  BusVolume: [
+    {
+      name: 'answers the volume of the bus it picks, as the run left it (#325)',
+      context: { busVolume: (bus: string) => (bus === 'bus-1' ? 0.4 : 1) },
+      inputs: { bus: 'bus-1' },
+      outputs: { volume: 0.4 },
+    },
+  ],
 };
 
 /** Two distinct handles that share a name – `Equals` must still tell them apart. */

tests/core/pattern.test.ts

@@ -55,6 +55,7 @@ describe('pattern asset (#333)', () => {
       'beats',
       'beat',
       'tempo',
+      'bus',
     ]);
   });
 

tests/core/song.test.ts

@@ -69,7 +69,13 @@ describe('the song asset (#334)', () => {
     const f = makeSong(1);
     expect(f.song().tracks.map((t) => t.name)).toEqual(['Track 1']);
     expect(f.song().items).toEqual([]);
-    expect(schemaForAsset(f.project, f.song()).map((d) => d.key)).toEqual(['tempo', 'beats', 'beat', 'grid']);
+    expect(schemaForAsset(f.project, f.song()).map((d) => d.key)).toEqual([
+      'tempo',
+      'beats',
+      'beat',
+      'grid',
+      'bus',
+    ]);
     expect(songGrid(f.song().props)).toBe(BAR);
     f.stack.execute(new SetAssetPropertyCommand(f.song().id, 'grid', '1/8T'));
     expect(songGrid(f.song().props)).toBe(160);

tests/core/soundfx.test.ts

@@ -474,6 +474,11 @@ function fakeAudio(): AudioSink & {
     tail: () => 0,
     stopVoice: () => {},
     stopOwner: () => {},
+    setMix: () => {},
+    setMixVolume: () => {},
+    mixVolume: () => 1,
+    resetMix: () => {},
+    tuneMix: () => {},
   };
   return sink;
 }

tests/core/sounds.test.ts

@@ -38,6 +38,7 @@ import {
   VOLUME_KEY,
   volumeOf,
 } from '../../src/core/properties/sounds';
+import { BUS_KEY } from '../../src/core/properties/buses';
 import { deserializeProject } from '../../src/core/store/serialize';
 import type { AudioSink } from '../../src/runtime/systems/Audio';
 import {
@@ -77,6 +78,11 @@ function fakeAudio(): AudioSink & {
     stop: (file: string) => sink.stopped.push(file),
     stopVoice: () => {},
     stopOwner: (owner: string) => sink.stoppedOwners.push(owner),
+    setMix: () => {},
+    setMixVolume: () => {},
+    mixVolume: () => 1,
+    resetMix: () => {},
+    tuneMix: () => {},
   };
   return sink;
 }
@@ -132,6 +138,7 @@ describe('the sound asset', () => {
       FADE_IN_CURVE_KEY,
       FADE_OUT_KEY,
       FADE_OUT_CURVE_KEY,
+      BUS_KEY,
     ]);
     expect(cutOf(asset.props)).toEqual({
       start: 0,

tests/editor/project-settings.test.ts

@@ -13,6 +13,8 @@ const before: ProjectSettings = {
   collisionLayers: ['Default', 'Enemies'],
   renderLayers: ['Default'],
   symbolScale: 1,
+  masterVolume: 1,
+  masterFx: '',
 };
 
 describe('project settings', () => {
@@ -70,4 +72,13 @@ describe('project settings', () => {
     expect(settingsChanges(before, { ...before, gameLinkZoom: 'fit' }).gameLinkZoom).toBe('fit');
     expect(settingsChanges(before, { ...before, gameLinkZoom: 'auto' }).gameLinkZoom).toBeUndefined();
   });
+
+  it('writes the master only where it changed, its volume held to 0..1 (#325)', () => {
+    expect(settingsChanges(before, { ...before, masterVolume: 0.5, masterFx: 'fx1' })).toEqual({
+      masterVolume: 0.5,
+      masterFx: 'fx1',
+    });
+    expect(settingsChanges(before, { ...before, masterVolume: 3 }).masterVolume).toBeUndefined();
+    expect(settingsChanges(before, { ...before, masterVolume: -1 }).masterVolume).toBe(0);
+  });
 });

tests/helpers.ts

@@ -214,6 +214,8 @@ export type FakeContext = NodeContext & {
     fx: string;
     fxParams: Readonly<Record<string, number>>;
     tempo: number;
+    /** The bus picked (#325); left out for none. */
+    bus?: string;
   }[];
   /** The notes the context was asked to play (#331); a voice's number is how many have been played. */
   notes: {
@@ -227,6 +229,7 @@ export type FakeContext = NodeContext & {
     tempo: number;
     fx: string;
     fxParams: Readonly<Record<string, number>>;
+    bus?: string;
   }[];
   /** The patterns the context was asked to play; a playing's number is how many have been played. */
   patterns: {
@@ -236,6 +239,7 @@ export type FakeContext = NodeContext & {
     detached: boolean;
     fx: string;
     fxParams: Readonly<Record<string, number>>;
+    bus?: string;
   }[];
   /** The songs the context was asked to play, numbered the same way. */
   songs: {
@@ -246,9 +250,18 @@ export type FakeContext = NodeContext & {
     detached: boolean;
     fx: string;
     fxParams: Readonly<Record<string, number>>;
+    bus?: string;
   }[];
   silenced: string[];
   tuned: { voice: number; fxParams: Readonly<Record<string, number>>; time: number; ease: EaseShare }[];
+  /** What buses the context was told to change (#325): a volume or FX parameters, in order. */
+  buses: {
+    bus: string;
+    volume?: number;
+    fxParams?: Readonly<Record<string, number>>;
+    time: number;
+    ease: EaseShare;
+  }[];
   /** The scenes the context was asked to load, in order. */
   loaded: string[];
   /** The time scale and the pause the context holds, as the game nodes left them. */
@@ -301,8 +314,8 @@ export function fakeContext(overrides: Partial<NodeContext> = {}): FakeContext {
     silenced: [],
     loaded: [],
     // The number of a voice is how many have been played: unique, and never 0.
-    playSound: (assetId, volume, loop, detached, fx, fxParams, tempo) =>
-      ctx.played.push({ assetId, volume, loop, detached, fx, fxParams, tempo }),
+    playSound: (assetId, volume, loop, detached, fx, fxParams, tempo, bus) =>
+      ctx.played.push({ assetId, volume, loop, detached, fx, fxParams, tempo, ...(bus && { bus }) }),
     notes: [],
     playNote: (
       instrumentId,
@@ -315,6 +328,7 @@ export function fakeContext(overrides: Partial<NodeContext> = {}): FakeContext {
       tempo,
       fx,
       fxParams,
+      bus,
     ) =>
       ctx.notes.push({
         instrumentId,
@@ -327,15 +341,16 @@ export function fakeContext(overrides: Partial<NodeContext> = {}): FakeContext {
         tempo,
         fx,
         fxParams,
+        ...(bus && { bus }),
       }),
     patterns: [],
-    playPattern: (patternId, volume, loop, detached, fx, fxParams) =>
-      ctx.patterns.push({ patternId, volume, loop, detached, fx, fxParams }),
+    playPattern: (patternId, volume, loop, detached, fx, fxParams, bus) =>
+      ctx.patterns.push({ patternId, volume, loop, detached, fx, fxParams, ...(bus && { bus }) }),
     stopPattern: (patternId, letRing) =>
       ctx.silenced.push(`pattern ${patternId}${letRing ? ' (let ring)' : ''}`),
     songs: [],
-    playSong: (songId, volume, fadeIn, loop, detached, fx, fxParams) =>
-      ctx.songs.push({ songId, volume, fadeIn, loop, detached, fx, fxParams }),
+    playSong: (songId, volume, fadeIn, loop, detached, fx, fxParams, bus) =>
+      ctx.songs.push({ songId, volume, fadeIn, loop, detached, fx, fxParams, ...(bus && { bus }) }),
     stopSong: (songId, fadeOut) => ctx.silenced.push(`song ${songId} (fade ${fadeOut})`),
     stopPlayback: (playback, fadeOut) => ctx.silenced.push(`playback ${playback} (fade ${fadeOut})`),
     // Every sound lasts a quarter of a second, as if it had been loaded.
@@ -347,6 +362,13 @@ export function fakeContext(overrides: Partial<NodeContext> = {}): FakeContext {
     stopVoice: (voice, letRing) => ctx.silenced.push(`voice ${voice}${letRing ? ' (let ring)' : ''}`),
     tuned: [],
     tuneSound: (voice, fxParams, time, ease) => ctx.tuned.push({ voice, fxParams, time, ease }),
+    buses: [],
+    tuneBus: (bus, fxParams, time, ease) => ctx.buses.push({ bus, fxParams, time, ease }),
+    setBusVolume: (bus, volume, time, ease) => ctx.buses.push({ bus, volume, time, ease }),
+    // The last volume set, else that of an asset nobody touched.
+    busVolume: (bus) =>
+      [...ctx.buses].reverse().find((change) => change.bus === bus && change.volume !== undefined)?.volume ??
+      1,
     loadScene: (sceneId) => ctx.loaded.push(sceneId),
     spawn: () => null,
     addJoint: () => null,

tests/viewport/render-layers.test.ts

@@ -135,6 +135,8 @@ describe('render layers (#302)', () => {
       collisionLayers: ['Default'],
       renderLayers: ['Default'],
       symbolScale: 1,
+      masterVolume: 1,
+      masterFx: '',
     };
     expect(settingsChanges(before, { ...before, renderLayers: ['Default'] })).toEqual({});
     expect(settingsChanges(before, { ...before, renderLayers: ['Default', 'UI'] })).toEqual({

tests/viewport/sound-library.test.ts

@@ -6,14 +6,16 @@
  * The device is stubbed – nothing makes a noise in a unit test, and Web Audio does not exist here.
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import type {
-  FxChipPlan,
-  FxEnvelopePlan,
-  FxPlan,
-  FxStage,
-  FxStagePlan,
-  FxVoice,
+import {
+  DRY_VOICE,
+  type FxChipPlan,
+  type FxEnvelopePlan,
+  type FxPlan,
+  type FxStage,
+  type FxStagePlan,
+  type FxVoice,
 } from '../../src/core/soundfx/nodes';
+import type { MixBus } from '../../src/core/music/mixer';
 import type { SequencePlay } from '../../src/core/music/playbacks';
 import type { ScheduledNote } from '../../src/core/music/Scheduler';
 import type { PitchOptions } from '../../src/viewport/fxWorklet';
@@ -105,6 +107,14 @@ let loadModule: () => Promise<void> = () => Promise.resolve();
 /** Whether a module has loaded: before that a worklet node cannot be made, as in a browser. */
 let moduleLoaded = false;
 
+/**
+ * The master every voice ends in (#325): made with the first voice that needs it, its input, level
+ * and pan out to the speakers, before the voice is connected into it.
+ */
+const INTO_MASTER = ['gain > gain', 'gain > panner', 'panner > destination', 'gain > gain'];
+/** What `busLevels` says of that master while nothing has set it. */
+const MASTER_LEVEL = { name: 'mix', gain: 1, pan: 0, into: null, fx: false, latency: 0 };
+
 const sources: FakeSource[] = [];
 /** Every `connect` made, as "from > to" by the kind of node – the order a voice is wired in. */
 const wires: string[] = [];
@@ -485,12 +495,13 @@ describe('the sound library', () => {
       duration: 1.5,
       at: 0,
       envelopes: 0,
+      bus: '',
     });
   });
 
   it('plays a dry voice straight into its volume, without loading the pitch worklet', async () => {
     await play(new SoundLibrary());
-    expect(wires).toEqual(['source > gain', 'gain > destination']);
+    expect(wires).toEqual(['source > gain', ...INTO_MASTER]);
     expect(sources[0]?.playbackRate.value).toBe(1);
     expect(modules).toEqual([]);
   });
@@ -505,7 +516,7 @@ describe('the sound library', () => {
       ],
     };
     await play(library, FILE, {}, fx);
-    expect(wires).toEqual(['pitch > gain', 'gain > filter', 'filter > gain', 'gain > destination']);
+    expect(wires).toEqual(['pitch > gain', 'gain > filter', 'filter > gain', ...INTO_MASTER]);
     expect(filters).toMatchObject([
       { type: 'lowshelf', frequency: { value: 80 }, gain: { value: 6 }, Q: { value: 1 } },
     ]);
@@ -540,7 +551,7 @@ describe('the sound library', () => {
     const crush: Chain = { pitch: 0, stages: [{ kind: 'crush', bits: 4, rate: 8000, mix: 0.5 }] };
     const voice = await play(library, FILE, {}, crush);
     expect(modules).toHaveLength(1);
-    expect(wires).toEqual(['source > crush', 'crush > gain', 'gain > destination']);
+    expect(wires).toEqual(['source > crush', 'crush > gain', ...INTO_MASTER]);
     const node = worklets[0]!;
     expect(node.options.parameterData).toEqual({ bits: 4, rate: 8000, mix: 0.5 });
     expect(library.levels(FILE)).toEqual([[4, 8000, 0.5]]);
@@ -592,7 +603,7 @@ describe('the sound library', () => {
       ],
     };
     const voice = await play(library, FILE, {}, { plan, params: {} });
-    expect(wires).toEqual(['source > phaser', 'phaser > flanger', 'flanger > gain', 'gain > destination']);
+    expect(wires).toEqual(['source > phaser', 'phaser > flanger', 'flanger > gain', ...INTO_MASTER]);
     const [phaser, flanger] = worklets as [FakeWorklet, FakeWorklet];
     expect(phaser.options.parameterData).toEqual({
       frequency: 800,
@@ -625,7 +636,7 @@ describe('the sound library', () => {
     const library = new SoundLibrary();
     await play(library, FILE, {}, { pitch: 0, stages: [{ kind: 'crush', bits: 4, rate: 8000, mix: 1 }] });
     expect(worklets).toHaveLength(0);
-    expect(wires).toEqual(['source > gain', 'gain > gain', 'gain > destination']);
+    expect(wires).toEqual(['source > gain', 'gain > gain', ...INTO_MASTER]);
     expect(library.stats()).toMatchObject({ started: 1, worklet: false });
   });
 
@@ -675,9 +686,9 @@ describe('the sound library', () => {
       'gain > gain',
       'gain > filter',
       'filter > gain',
-      'gain > destination',
+      ...INTO_MASTER,
     ]);
-    expect(gains.map((g) => g.value)).toEqual([1, 1, 0.75, expect.closeTo(0.5), 0.25]);
+    expect(gains.map((g) => g.value)).toEqual([1, 1, 0.75, expect.closeTo(0.5), 0.25, 1, 1]);
     expect(sources.map((s) => s.started)).toEqual([true]);
     expect(library.stats()).toMatchObject({ playing: 1, started: 1, last: { pitches: [12, 0], stages: 2 } });
 
@@ -996,10 +1007,10 @@ describe('the sound library', () => {
         'gain > delay', // at the feedback
         'gain > gain', // the fade into the echo
         'gain > gain',
-        'gain > destination',
+        ...INTO_MASTER,
       ]);
-      // The voice, the fade made before it, the echo's in, out, feedback and mix.
-      expect(gains.map((g) => g.value)).toEqual([1, 1, 1, 1, 0.4, 0.5]);
+      // The voice, the fade made before it, the echo's in, out, feedback and mix, then the master's two.
+      expect(gains.map((g) => g.value)).toEqual([1, 1, 1, 1, 0.4, 0.5, 1, 1]);
     });
 
     it('wires a ping-pong echo into the left only, crossing sides on every round', async () => {
@@ -1156,7 +1167,8 @@ describe('the sound library', () => {
       library.tune(voice, { time: 0.5, dull: 1, wet: 0.2 }, 2);
       expect(delays[0]!.delayTime.ramps).toEqual([['linear', 0.5, 2]]);
       expect(filters[0]!.frequency.ramps).toEqual([['exponential', expect.closeTo(500), 2]]);
-      expect(gains.at(-1)!.ramps).toEqual([['linear', 0.2, 2]]);
+      // The mix of the echo, made before the master's two.
+      expect(gains.at(-3)!.ramps).toEqual([['linear', 0.2, 2]]);
       expect(library.levels(FILE)).toEqual([[0.25, 0.4, 20000, 0.5]]);
     });
   });
@@ -1188,15 +1200,9 @@ describe('notes of an instrument (#331)', () => {
     expect(library.stats()).toMatchObject({ started: 1, playing: 1, decoded: 2 });
     expect(library.stats().last).toMatchObject({ file: 'instrument:i', layers: 2, duration: 1.5 });
     expect(sources.map((source) => source.started)).toEqual([true, true]);
-    // Voice gain first, then a fade per way at the sound's volume.
-    expect(gains.map((gain) => gain.value)).toEqual([1, 0.5, 0.5]);
-    expect(wires).toEqual([
-      'source > gain',
-      'gain > gain',
-      'source > gain',
-      'gain > gain',
-      'gain > destination',
-    ]);
+    // Voice gain first, then a fade per way at the sound's volume, then the master's two.
+    expect(gains.map((gain) => gain.value)).toEqual([1, 0.5, 0.5, 1, 1]);
+    expect(wires).toEqual(['source > gain', 'gain > gain', 'source > gain', 'gain > gain', ...INTO_MASTER]);
   });
 
   it('a release fades out the ways that end with the note and lets a one-shot play on', async () => {
@@ -1365,8 +1371,8 @@ describe('notes with an Envelope (#335)', () => {
     expect(driver().started).toBe(true);
     expect(driver().offset.ramps).toEqual([['linear', 1, 0.1]]);
     expect(driver().offset.glides).toEqual([0.5]);
-    // Voice gain, the Sample's volume, and the Envelope's gain, which is all the curve.
-    expect(gains.map((gain) => gain.value)).toEqual([1, 0.5, 0]);
+    // Voice gain, the Sample's volume, and the Envelope's gain, which is all the curve; then the master's.
+    expect(gains.map((gain) => gain.value)).toEqual([1, 0.5, 0, 1, 1]);
     expect(wires).toContain('clock > shaper');
     expect([shapers[0]!.curve![512], shapers[0]!.curve![1024]]).toEqual([0, 1]);
   });
@@ -1435,7 +1441,8 @@ describe('notes with an Envelope (#335)', () => {
 
     const cut = await note(library, way(true));
     library.stopVoice(cut);
-    expect(gains[3]!.ramps).toEqual([['linear', 0, 0.01]]);
+    // After the first note's three and the master's two.
+    expect(gains[5]!.ramps).toEqual([['linear', 0, 0.01]]);
     expect(library.playing(cut)).toBe(false);
   });
 
@@ -1638,7 +1645,9 @@ describe('clips and tracks of a song (#334)', () => {
     expect(gains[1]!.glides).toEqual([0.5]);
     expect(panners[0]!.glides).toEqual([-0.25]);
     library.setBus('song:s:t', 0, 1);
-    expect(panners).toHaveLength(1);
+    // The track's and the master's it goes into (#325); no new one for the same track.
+    expect(panners).toHaveLength(2);
+    expect(wires).toContain('panner > gain');
     expect([gains[1]!.glides, panners[0]!.glides]).toEqual([
       [0.5, 0],
       [-0.25, 1],
@@ -1711,14 +1720,19 @@ describe('the patterns and songs a game plays (#336)', () => {
       sequence((note) => (struck.push(note), 0)),
       'logic',
     );
+    // The master of the project is made on the way, the one all of it is heard through (#325).
     expect(library.busLevels()).toEqual([
-      { name: `play:${id}`, gain: 0, pan: 0, into: null, fx: false, latency: 0 },
+      MASTER_LEVEL,
+      { name: `play:${id}`, gain: 0, pan: 0, into: 'mix', fx: false, latency: 0 },
       { name: `play:${id}:song:s:t`, gain: 0.25, pan: -1, into: `play:${id}`, fx: false, latency: 0 },
     ]);
     expect(wires).toEqual([
+      'gain > gain',
+      'gain > panner',
       'gain > gain',
       'gain > panner',
       'panner > destination',
+      'panner > gain',
       'gain > gain',
       'gain > panner',
       'panner > gain',
@@ -1733,7 +1747,7 @@ describe('the patterns and songs a game plays (#336)', () => {
     library.stopSequence('song:', false, 0);
     expect(library.playbacks()).toEqual([]);
     clockTo();
-    expect(library.busLevels()).toEqual([]);
+    expect(library.busLevels()).toEqual([MASTER_LEVEL]);
     expect(disconnects.filter((kind) => kind !== 'clock')).toEqual([
       'gain',
       'gain',
@@ -1755,7 +1769,7 @@ describe('the patterns and songs a game plays (#336)', () => {
     expect(() => library.playbacks()).not.toThrow();
     expect(library.playbacks()).toEqual([]);
     clockTo();
-    expect(library.busLevels()).toEqual([]);
+    expect(library.busLevels()).toEqual([MASTER_LEVEL]);
   });
 
   it('a playing without notes or clips is none', () => {
@@ -1928,7 +1942,7 @@ describe('a sound FX on a bus (#346)', () => {
     clockTo();
     expect(shifter.posted).toEqual(['stop']);
     expect(shifter.disconnected).toBe(true);
-    expect(library.busLevels()).toEqual([]);
+    expect(library.busLevels()).toEqual([MASTER_LEVEL]);
   });
 
   it('makes the chain of a track in the Song tab once, and again only for another sound FX', async () => {
@@ -1946,7 +1960,8 @@ describe('a sound FX on a bus (#346)', () => {
     expect(library.busLatency('song:s:t')).toBeCloseTo(LATE, 12);
     await library.setBuses([{ ...track, fx: undefined }]);
     expect(library.busLevels()).toEqual([
-      { name: 'song:s:t', gain: 1, pan: 0, into: null, fx: false, latency: 0 },
+      MASTER_LEVEL,
+      { name: 'song:s:t', gain: 1, pan: 0, into: 'mix', fx: false, latency: 0 },
     ]);
   });
 
@@ -1956,10 +1971,98 @@ describe('a sound FX on a bus (#346)', () => {
     library.releaseBuses(['song:s:t']);
     await library.setBuses([{ name: 'song:s:t', gain: 1, pan: 0, fx: voice(up) }]);
     clockTo();
-    expect(library.busLevels().map((bus) => bus.name)).toEqual(['song:s:t']);
+    expect(library.busLevels().map((bus) => bus.name)).toEqual(['mix', 'song:s:t']);
     library.releaseBuses(['song:s:t']);
     clockTo();
-    expect(library.busLevels()).toEqual([]);
+    expect(library.busLevels()).toEqual([MASTER_LEVEL]);
     expect(worklets[0]!.posted).toEqual(['stop']);
   });
 });
+
+describe('the master and the buses of the project (#325)', () => {
+  const bus = (name: string, volume: number, into: string | null, fx: FxVoice | null = null): MixBus => ({
+    name,
+    volume,
+    into,
+    fx,
+  });
+  const mix = [bus('mix', 0.5, null), bus('mix:a', 1, 'mix'), bus('mix:b', 0.25, 'mix:a')];
+  const levels = (library: SoundLibrary) =>
+    library.busLevels().map(({ name, gain, into }) => ({ name, gain, into }));
+
+  it('makes nothing before there is a context, then the master and every bus into the one it names', async () => {
+    const library = new SoundLibrary();
+    await library.setMix(mix);
+    expect(wires).toEqual([]);
+    await play(library);
+    expect(levels(library)).toEqual([
+      { name: 'mix', gain: 0.5, into: null },
+      { name: 'mix:a', gain: 1, into: 'mix' },
+      { name: 'mix:b', gain: 0.25, into: 'mix:a' },
+    ]);
+    expect(wires.filter((wire) => wire.endsWith('> destination'))).toEqual(['panner > destination']);
+  });
+
+  it('plays a voice on the bus it is given, and a playing too', async () => {
+    const library = new SoundLibrary();
+    await library.setMix(mix);
+    library.play(FILE, 1, false, '', DRY_VOICE, 'mix:b');
+    await settle();
+    await arrive();
+    expect(library.stats().last?.bus).toBe('mix:b');
+    const id = library.playSequence(
+      'pattern:p',
+      {
+        sequence: { notes: [{ tick: 0, length: 480, velocity: 1, instrument: 'i', note: 60 }] },
+        tempo: 120,
+        length: 1920,
+        loop: null,
+        needs: { layers: [], files: [] },
+        bus: 'mix:a',
+        strike: () => 0,
+      },
+      '',
+    );
+    expect(library.busLevels().find((level) => level.name === `play:${id}`)?.into).toBe('mix:a');
+  });
+
+  it('sends a bus on into another one when the mix says so, and lets one go whose asset is gone', async () => {
+    const library = new SoundLibrary();
+    await library.setMix(mix);
+    await play(library);
+    await library.setMix([mix[0]!, mix[1]!, { ...mix[2]!, into: 'mix' }]);
+    expect(levels(library).at(-1)).toEqual({ name: 'mix:b', gain: 0.25, into: 'mix' });
+    await library.setMix([mix[0]!, mix[1]!]);
+    clockTo();
+    expect(levels(library).map((level) => level.name)).toEqual(['mix', 'mix:a']);
+  });
+
+  it('holds the volume a game sets over that of the asset until it is reset, gliding there over its time', async () => {
+    const library = new SoundLibrary();
+    await library.setMix(mix);
+    await play(library);
+    library.setMixVolume('mix:b', 0.8, 1.5);
+    expect(gains.some((gain) => gain.ramps.some((ramp) => ramp[0] === 'linear' && ramp[1] === 0.8))).toBe(
+      true,
+    );
+    expect(library.mixVolume('mix:b')).toBe(0.8);
+    await library.setMix([mix[0]!, mix[1]!, { ...mix[2]!, volume: 0.1 }]);
+    expect([library.mixVolume('mix:b'), levels(library).at(-1)!.gain]).toEqual([0.8, 0.8]);
+    library.resetMix();
+    expect([library.mixVolume('mix:b'), levels(library).at(-1)!.gain]).toEqual([0.1, 0.1]);
+    expect(library.mixVolume('mix')).toBe(0.5);
+  });
+
+  it('changes the sound FX of a bus of the mix, and says so only for one that is there', async () => {
+    const library = new SoundLibrary();
+    const plan: FxPlan = {
+      pitch: [],
+      stages: [{ kind: 'crush', bits: { value: 8, param: 'b' }, rate: { value: 8000 }, mix: { value: 1 } }],
+    };
+    await play(library);
+    await library.setMix([bus('mix', 1, null, { plan, params: {}, tempo: 120 })]);
+    expect(library.tuneMix('mix', { b: 3 }, 0.5)).toBe(true);
+    expect(worklets[0]!.parameters.get('bits')!.ramps).toEqual([['linear', 3, 0.5]]);
+    expect(library.tuneMix('mix:gone', { b: 3 })).toBe(false);
+  });
+});