Change the sound FX parameters of a sound while it plays #315

Until now a value handed to a sound FX counted from the start of the
voice only. An engine whose pitch follows the speed, or a loop that
gets quieter, could not be built. Every play of Play sound now gives
out the number of its voice, and a new node lets the knobs of that one
voice glide to new values while it plays.

- Play sound has a new output voice: the number of this one play, or 0
  where nothing was played. Kept in a Number variable it reaches the
  voice from another event. Two plays of one sound are two voices.
- New action node Set sound FX parameters (exec, voice, fx params).
  It reaches exactly the voice it is given, a detached one too. A
  voice that has ended, or voice 0, is not reached.
- AudioSink.play returns the voice number and takes the plan and the
  values (FxVoice) instead of a finished chain. AudioSink.tune takes a
  voice number and new values. A name the voice's FX does not have is
  left out, one not given keeps its value.
- SoundLibrary hands out the number at once, before the bytes are
  there, and never twice. A voice still waiting for its bytes starts
  with the values handed in meanwhile.
- Every knob of a voice moves with setTargetAtTime (30 ms time
  constant). A knob whose value did not change is not sent again, so a
  tune every frame costs next to nothing.
- A pitch on a playing voice glides by playbackRate. A new WSOLA copy
  in the middle of a sound is not worked out, so the voice gets shorter
  or longer while it is moved. On a loop that is not heard.
- fxChainOf now gives a chain whose shape depends on the plan alone.
  A stage fed by a parameter stays at 0 dB, and a Mix fed by a
  parameter keeps both ways. A typed-in 0 or Mix at 0/1 is still left
  out by the compiler.
- Every way of a voice has a source of its own, also at the same
  pitch, so each can glide on its own. The pitched copy is shared.
- The tab keeps the numbers of what it plays, so moving a parameter
  field is heard at once.
- Test hook __gm.sound.levels(file) reads the knobs of every voice of
  a file, oldest first, and stats() counts the voices tuned.

Tests:
- soundfx.test.ts: 29 tests (+2 for the node in a running world: the
  voice of the first of two plays of one sound, and a play that played
  nothing)
- sound-library.test.ts: 15 tests (+3: glide, reach by number,
  pending voice)
- node-catalog.test.ts: 370 tests (+2, Play sound checks its voice)
- sounds + keep-on-scene-load: 31 tests, unchanged
- Counter-test: a tune that reaches every voice of the same file makes
  the reach test fail.
- e2e 34 (melektaus-atx): ALL PASSED - 30 checks (+1). In Chrome two
  looping voices of one sound start at depth 7. The one whose number
  sits in a variable glides to 0.7938 (2^(-4/12) = 0.7937), the other
  stays at 1. Both gains stay at 0.5012.
- The gate ran before voices got a number (CHECK EXIT 0, 241 files,
  3658 tests), not after.

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

src/editor/debugHook.ts

@@ -41,6 +41,8 @@ export function installDebugHook(app: Application, state: EditorState, editor: E
     sound: {
       stats: () => soundLibrary.stats(),
       duration: (file: string) => soundLibrary.duration(file),
+      /** Where the knobs of each voice of that file are now, oldest first, a pitch as its speed (#315). */
+      levels: (file: string) => soundLibrary.levels(file),
       /** Decodes ahead of a check, so a play can be asserted without racing the network. */
       load: (file: string) => soundLibrary.load(file).then((buffer) => buffer?.duration ?? null),
       stopAll: () => soundLibrary.stopAll(),

src/editor/soundfx/SoundFxEditor.ts

@@ -3,7 +3,6 @@ import { findAssetOf } from '../../core/model/Project';
 import { resolveAssetProps } from '../../core/properties/resolve';
 import { volumeOf } from '../../core/properties/sounds';
 import { soundFxBuildFor, soundFxParams } from '../../core/soundfx/compile';
-import { fxChainOf } from '../../core/soundfx/nodes';
 import { Button, Dropdown, HStack, Label, Menu, NumberField, Stack, Theme } from '../../ui';
 import { soundLibrary } from '../../viewport/SoundLibrary';
 import { AssetTabEditor } from '../AssetTabEditor';
@@ -40,6 +39,8 @@ export class SoundFxEditor extends AssetTabEditor<SoundFxAsset, GraphCanvas> {
   private defaults: Record<string, number> = {};
   private paramsKey = '';
   private valuesFor = '';
+  /** The voices the tab started that may still be playing – what a moved field reaches. */
+  private voices: number[] = [];
 
   constructor(state: EditorState) {
     super(state, { infoWidth: INFO_WIDTH });
@@ -89,8 +90,8 @@ export class SoundFxEditor extends AssetTabEditor<SoundFxAsset, GraphCanvas> {
   /** Sets one parameter the header plays with, as typing into its field does. */
   setPreviewValue(key: string, value: number): void {
     if (!(key in this.values)) return;
-    this.values[key] = value;
     this.paramFields.get(key)?.setNumber(value);
+    this.setValue(key, value);
   }
 
   /** Plays the picked sound through the graph; a graph that does not compile is not played at all. */
@@ -100,11 +101,22 @@ export class SoundFxEditor extends AssetTabEditor<SoundFxAsset, GraphCanvas> {
     const plan = asset && soundFxBuildFor(asset).compiled;
     if (!sound?.file || !plan) return;
     const volume = volumeOf(resolveAssetProps(this.state.project, sound));
-    soundLibrary.play(sound.file, volume, false, PREVIEW_OWNER, fxChainOf(plan, this.values));
+    const voice = soundLibrary.play(sound.file, volume, false, PREVIEW_OWNER, {
+      plan,
+      params: { ...this.values },
+    });
+    if (voice) this.voices.push(voice);
+  }
+
+  /** A moved field is heard at once on what the tab is playing (#315); an ended voice is let go. */
+  private setValue(key: string, value: number): void {
+    this.values[key] = value;
+    this.voices = this.voices.filter((voice) => soundLibrary.tune(voice, { [key]: value }));
   }
 
   stop(): void {
     soundLibrary.stopOwner(PREVIEW_OWNER);
+    this.voices = [];
   }
 
   protected override infoText(asset: SoundFxAsset): string {
@@ -152,8 +164,8 @@ export class SoundFxEditor extends AssetTabEditor<SoundFxAsset, GraphCanvas> {
         const field = new NumberField(values[port.key], {
           width: PARAM_WIDTH,
           step: 0.1,
-          onInput: (value) => (this.values[port.key] = value),
-          onChange: (value) => (this.values[port.key] = value),
+          onInput: (value) => this.setValue(port.key, value),
+          onChange: (value) => this.setValue(port.key, value),
         });
         this.paramFields.set(port.key, field);
         this.paramBar.add(field);