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/runtime/GameRun.ts

@@ -5,6 +5,7 @@
 import type { SaveArea } from '../core/graph/savedValues';
 import type { SceneAsset } from '../core/model/Asset';
 import { findScene, type Project } from '../core/model/Project';
+import { mixOf } from '../core/music/mixer';
 import type { AudioSink } from './systems/Audio';
 import { addGameSystems, type BehaviorSystem, type TimeScaled } from './systems/BehaviorSystem';
 import type { Input } from './systems/Input';
@@ -40,6 +41,9 @@ export class GameRun {
   static start(project: Project, sceneId: string, input: Input, services: RunServices): GameRun {
     const scene = findScene(project, sceneId);
     const before = scene && structuredClone<StoredObjects>({ objects: scene.objects, groups: scene.groups });
+    // Every run starts with the buses as their assets have them (#325).
+    services.audio.resetMix();
+    services.audio.setMix(mixOf(project));
     const world = World.instantiate(project, sceneId);
     const run = new GameRun(project, input, services, world, addGameSystems(world, project, input, services));
     if (before) run.stored.set(sceneId, before);
@@ -99,6 +103,7 @@ export class GameRun {
    */
   end(): void {
     this.world.destroy();
+    this.services.audio.resetMix();
     for (const [sceneId, before] of this.stored) {
       const scene = findScene(this.project, sceneId);
       if (scene) restore(scene, before);

src/runtime/systems/Audio.ts

@@ -1,5 +1,6 @@
 import type { EaseShare } from '../../core/model/animation';
 import type { SequencePlay } from '../../core/music/playbacks';
+import type { MixBus } from '../../core/music/mixer';
 import type { FxParams, FxPlan, FxVoice } from '../../core/soundfx/nodes';
 
 /**
@@ -17,9 +18,10 @@ export interface AudioSink {
    * with it, because a sound is something a thing in the world is doing, not a thing of its own.
    * `''` means the voice has no owner and outlives whatever started it. `fx` is the sound FX the
    * voice passes on its way out (#311), with the values of its parameters; `DRY_VOICE` passes none.
-   * Returns the number of the voice, never used twice, or 0 where nothing is going to play.
+   * Returns the number of the voice, never used twice, or 0 where nothing is going to play. `bus` is
+   * the bus of the mix it is heard on (#325), the master where left out.
    */
-  play(file: string, volume: number, loop: boolean, owner: string, fx?: FxVoice): number;
+  play(file: string, volume: number, loop: boolean, owner: string, fx?: FxVoice, bus?: string): number;
   /**
    * Starts one note of an instrument (#331), as `play` starts a sound: `layers` are what the note is
    * made of, played side by side as one voice, each way reading the file of its own source. `name`
@@ -88,6 +90,19 @@ export interface AudioSink {
   stopVoice(voice: number, letRing?: boolean): void;
   /** Silences every voice started by that owner – what destroying a behavior does. */
   stopOwner(owner: string): void;
+  /**
+   * The master and the buses of the project (#325), set as a run starts. What a game set a level to
+   * holds over it until `resetMix`.
+   */
+  setMix(buses: readonly MixBus[]): void;
+  /** The level a game sets a bus of the mix to, over `time` seconds along `ease`. */
+  setMixVolume(bus: string, volume: number, time?: number, ease?: EaseShare): void;
+  /** The level a bus of the mix is at: what a game set, else that of its asset. */
+  mixVolume(bus: string): number;
+  /** Every level back to that of its asset: a run starts afresh. */
+  resetMix(): void;
+  /** Hands new values to the sound FX of a bus of the mix, as `tune` does to a voice. */
+  tuneMix(bus: string, params: FxParams, time?: number, ease?: EaseShare): void;
 }
 
 /**
@@ -97,7 +112,7 @@ export interface AudioSink {
 export interface NoteTiming {
   at?: number;
   tempo?: number;
-  /** The track of a song it is heard on (#334); straight out where left out. */
+  /** The bus it is heard on: a track of a song (#334) or one of the mix (#325); the master where left out. */
   bus?: string;
 }
 
@@ -124,4 +139,9 @@ export const SILENT_AUDIO: AudioSink = {
   stop: () => {},
   stopVoice: () => {},
   stopOwner: () => {},
+  setMix: () => {},
+  setMixVolume: () => {},
+  mixVolume: () => 1,
+  resetMix: () => {},
+  tuneMix: () => {},
 };

src/runtime/systems/behaviorContext.ts

@@ -31,6 +31,7 @@ import {
   SOUND_ITEM_MAX_DB,
 } from '../../core/music/song';
 import { songBuses } from '../../core/music/songBuses';
+import { playedBus, reachedBus } from '../../core/music/mixer';
 import { DRY_VOICE, type FxParams, type FxVoice } from '../../core/soundfx/nodes';
 import type { Entity } from '../Entity';
 import { PhysicsSystem } from '../physics/PhysicsSystem';
@@ -179,23 +180,23 @@ export function behaviorContext(
       // eslint-disable-next-line no-console
       console.log(`[behavior ${entity.name}]`, message);
     },
-    playSound: (assetId, volume, loop, detached, fx, fxParams, tempo) =>
-      playSound(run, assetId, volume, loop, detached ? '' : entity.id, fx, fxParams, tempo),
-    playNote: (instrumentId, note, velocity, volume, duration, detached, params, tempo, fx, fxParams) =>
+    playSound: (assetId, volume, loop, detached, fx, fxParams, tempo, bus) =>
+      playSound(run, assetId, volume, loop, detached ? '' : entity.id, fx, fxParams, tempo, bus),
+    playNote: (instrumentId, note, velocity, volume, duration, detached, params, tempo, fx, fxParams, bus) =>
       playNote(
         run,
         instrumentId,
         { note, velocity, volume, duration },
         detached ? '' : entity.id,
         params,
-        { tempo },
+        { tempo, bus: instrumentBus(project, instrumentId, bus) },
         fxVoiceOf(project, fx, tempo, fxParams),
       ),
-    playPattern: (patternId, volume, loop, detached, fx, fxParams) =>
-      playPattern(run, patternId, volume, loop, detached ? '' : entity.id, fx, fxParams),
+    playPattern: (patternId, volume, loop, detached, fx, fxParams, bus) =>
+      playPattern(run, patternId, volume, loop, detached ? '' : entity.id, fx, fxParams, bus),
     stopPattern: (patternId, letRing) => run.audio.stopSequence(patternVoiceName(patternId), letRing),
-    playSong: (songId, volume, fadeIn, loop, detached, fx, fxParams) =>
-      playSong(run, songId, volume, fadeIn, loop, detached ? '' : entity.id, fx, fxParams),
+    playSong: (songId, volume, fadeIn, loop, detached, fx, fxParams, bus) =>
+      playSong(run, songId, volume, fadeIn, loop, detached ? '' : entity.id, fx, fxParams, bus),
     stopSong: (songId, fadeOut) => run.audio.stopSequence(songVoiceName(songId), false, heldFade(fadeOut)),
     stopPlayback: (playback, fadeOut) => run.audio.stopPlayback(playback, heldFade(fadeOut)),
     soundLength: (assetId) => {
@@ -211,6 +212,18 @@ export function behaviorContext(
     },
     stopVoice: (voice, letRing) => run.audio.stopVoice(voice, letRing),
     tuneSound: (voice, fxParams, time, ease) => run.audio.tune(voice, withScoped(fxParams), time, ease),
+    tuneBus: (bus, fxParams, time, ease) => {
+      const reached = reachedBus(project, bus);
+      if (reached) run.audio.tuneMix(reached, fxParams, time, ease);
+    },
+    setBusVolume: (bus, volume, time, ease) => {
+      const reached = reachedBus(project, bus);
+      if (reached) run.audio.setMixVolume(reached, volume, time, ease);
+    },
+    busVolume: (bus) => {
+      const reached = reachedBus(project, bus);
+      return reached ? run.audio.mixVolume(reached) : 0;
+    },
     spawn: (assetId, position, parent) => world.spawn(assetId, position, resolve(parent) ?? null),
     addJoint: (assetId, owner, connected, at) => {
       const on = resolve(owner);
@@ -268,6 +281,7 @@ function playSound(
   fxId: string,
   fxParams: FxParams,
   tempo: number,
+  bus: string,
 ): number {
   const asset = findAssetOf(project, assetId, 'sound');
   if (!asset?.file) return 0;
@@ -281,9 +295,15 @@ function playSound(
     loop ?? loopsOf(props),
     owner,
     plan ? { plan, params: fxParams, tempo } : DRY_VOICE,
+    playedBus(project, bus, props),
   );
 }
 
+/** The bus of the mix a note of that instrument is heard on, by the pick of a node (#325). */
+export function instrumentBus(project: Project, instrumentId: string, picked: string): string {
+  return playedBus(project, picked, findAssetOf(project, instrumentId, 'instrument')?.props ?? {});
+}
+
 /**
  * One note of an instrument (#331), as the sink understands it: the layers the instrument makes of
  * it, the velocity as loudness and as the value of its `velocity`, and the voice's volume held to
@@ -345,6 +365,7 @@ function playPattern(
   owner: string,
   fxId: string,
   fxParams: FxParams,
+  bus: string,
 ): number {
   const asset = findAssetOf(project, patternId, 'pattern');
   if (!asset) return 0;
@@ -364,6 +385,7 @@ function playPattern(
       loop: loop ? { start: 0, end: length } : null,
       needs: sequenceNeeds(project, sequence),
       ...(fx && { fx }),
+      bus: playedBus(project, bus, asset.props),
       strike: (note) => strikeNote({ project, audio }, { ...note, volume: level }, owner),
     },
     owner,
@@ -385,6 +407,7 @@ function playSong(
   owner: string,
   fxId: string,
   fxParams: FxParams,
+  bus: string,
 ): number {
   const song = findAssetOf(project, songId, 'song');
   if (!song) return 0;
@@ -403,6 +426,7 @@ function playSong(
       fadeIn: heldFade(fadeIn),
       buses: songBuses(project, song),
       ...(fx && { fx }),
+      bus: playedBus(project, bus, song.props),
       strike: (note) => strikeNote({ project, audio }, note, owner),
       strikeClip: (clip) => playClip({ project, audio }, clip),
     },