Play and stop a song from a behavior in the game #336

A song could only be heard in its tab. Now a game plays it through
Play song and ends it through Stop song, with its tracks as they are
set. A playing pattern or song also no longer undoes the pause of the
toolbar.

- Play song plays from the start of the song and then round the loop
  of its ruler, so an intro is heard once. Without loop it plays once
  to its end. Inputs are song, volume, fade in, loop (on by default)
  and detached (off by default). It gives out playback.
- Stop song stops one song, every song for none, or one playback by
  its number, over its fade out. Stop sound with no sound named stops
  songs too. Stop pattern with no pattern named stops only patterns.
- Songs play side by side, as patterns do. They are owned like a
  sound, so leaving the scene ends one unless it is detached. Pause
  game and the time scale leave the music alone.
- Each playing is heard through a master of its own, silent until its
  first note. The fades move it, and a song's tracks sit inside it on
  buses of their own. They go once the playing and its voices have.
- Notes and clips are struck the same way in the editor and the game
  (strikeNote, playClip). What a sequence needs comes from one place
  (core/music/needs).

Findings:
- Reading the audio clock resumed a suspended context. A playing
  pattern read it every 25 ms and so undid the toolbar's pause. The
  library now leaves a context alone while the toolbar holds it.
- A pattern played once to its end asked the list of playings about
  its voices, and that list asked the pattern again. Once its last
  voice was gone this ran until the stack overflowed. The scheduler of
  a playing now asks only after voices.
- e2e 64 reads the playings through __gm.sound.playbacks() now.

Tests:
- song-play.test.ts (new): 8 tests, node catalog +8 cases
- sound-library.test.ts: 66 tests, 4 new
- e2e 64 (melektaus-atx): 23 of 23 checks passed
- e2e 65 (melektaus-atx): ALL PASSED, 22 checks (+4)
- Gate (melektaus-atx): CHECK EXIT 0, 251 files, 3903 tests
- Counter-checks: the old way of asking after voices, a clock read
  that wakes a held context, and a start after a fade out began each
  fail 1 test

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

tests/viewport/sound-library.test.ts

@@ -7,6 +7,8 @@
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { FxEnvelopePlan, FxPlan, FxStage, FxStagePlan, FxVoice } from '../../src/core/soundfx/nodes';
+import type { SequencePlay } from '../../src/core/music/playbacks';
+import type { ScheduledNote } from '../../src/core/music/Scheduler';
 import type { PitchOptions } from '../../src/viewport/pitchWorklet';
 import { SoundLibrary } from '../../src/viewport/SoundLibrary';
 
@@ -1413,3 +1415,95 @@ describe('clips and tracks of a song (#334)', () => {
     expect(library.peaks(FILE)).toBe(peaks);
   });
 });
+
+describe('the patterns and songs a game plays (#336)', () => {
+  /** A sequence of a note on a track and one on a track the song does not have, both at its start. */
+  function sequence(
+    strike: (note: ScheduledNote) => number,
+    fields: Partial<SequencePlay> = {},
+  ): SequencePlay {
+    const note = { tick: 0, length: 480, velocity: 1, instrument: 'i' };
+    return {
+      sequence: {
+        notes: [
+          { ...note, note: 60, bus: 'song:s:t' },
+          { ...note, note: 62, bus: 'song:s:gone' },
+        ],
+      },
+      tempo: 120,
+      length: 1920,
+      loop: null,
+      needs: { layers: [], files: [] },
+      volume: 0.5,
+      fadeIn: 2,
+      buses: [{ name: 'song:s:t', gain: 0.25, pan: -1 }],
+      strike,
+      ...fields,
+    };
+  }
+
+  it('hears each playing through a master of its own, silent until it starts, its tracks into it', async () => {
+    const library = new SoundLibrary();
+    const struck: ScheduledNote[] = [];
+    const id = library.playSequence(
+      'song:s',
+      sequence((note) => (struck.push(note), 0)),
+      'logic',
+    );
+    expect(library.busLevels()).toEqual([
+      { name: `play:${id}`, gain: 0, pan: 0 },
+      { name: `play:${id}:song:s:t`, gain: 0.25, pan: -1 },
+    ]);
+    expect(wires).toEqual(['gain > panner', 'panner > destination', 'gain > panner', 'panner > gain']);
+    await settle();
+    expect(struck.map((note) => note.bus)).toEqual([`play:${id}:song:s:t`, `play:${id}`]);
+    // It rises from silence with its first note, 50 ms ahead, to its volume over its fade in.
+    expect(gains[0]!.ramps).toEqual([
+      ['set', 0, 0.05],
+      ['linear', 0.5, 2.05],
+    ]);
+    library.stopSequence('song:', false, 0);
+    expect(library.playbacks()).toEqual([]);
+    clockTo();
+    expect(library.busLevels()).toEqual([]);
+    expect(disconnects.filter((kind) => kind !== 'clock')).toEqual(['gain', 'panner', 'gain', 'panner']);
+  });
+
+  it('is gone once played to its end, its last voice gone too – asking after it does not ask itself', async () => {
+    const library = new SoundLibrary();
+    library.playSequence(
+      'pattern:p',
+      sequence(() => 77, { length: 10, buses: [] }),
+      '',
+    );
+    await settle();
+    expect(() => library.playbacks()).not.toThrow();
+    expect(library.playbacks()).toEqual([]);
+    clockTo();
+    expect(library.busLevels()).toEqual([]);
+  });
+
+  it('a playing without notes or clips is none', () => {
+    const library = new SoundLibrary();
+    const empty = sequence(() => 1, { sequence: { notes: [], clips: [] } });
+    expect(library.playSequence('song:s', empty, '')).toBe(0);
+    expect(library.busLevels()).toEqual([]);
+  });
+
+  it('nothing that reads the clock wakes it while the toolbar holds it', () => {
+    const library = new SoundLibrary();
+    library.time();
+    let resumes = 0;
+    (library as unknown as { context: { resume: () => Promise<void> } }).context.resume = () => {
+      resumes += 1;
+      return Promise.resolve();
+    };
+    contextState = 'suspended';
+    library.setSuspended(true);
+    library.time();
+    expect(resumes).toBe(0);
+    library.setSuspended(false);
+    library.time();
+    expect(resumes).toBe(2);
+  });
+});