Merge pull request #52 from boostcampwm-snu-2026-1/feat/43-mixer-audio-routing

feat: route arrangement playback through mixer

Author: britle20

docs/audio-engine.md

@@ -135,6 +135,10 @@ Implementation names may differ. React components should not hold or mutate Web
 
 Level meters are display feedback only. The UI may poll meter snapshots with `requestAnimationFrame` or subscribe through an audio-engine callback. Meter timing must not drive audio scheduling.
 
+The current browser engine exposes meter snapshots as normalized runtime values from track and master `AnalyserNode` instances. These snapshots are display data only and are not serializable project state.
+
+The first mixer routing path applies to track-aware `SONG` arrangement events. Preview and `PAT` playback may continue using the existing direct playback path unless a later feature explicitly adds clip-editor mixer routing.
+
 ## One-shot Sample Playback
 
 Use a new `AudioBufferSourceNode` for every one-shot playback. A source node cannot be restarted after it has played.

docs/data-model.md

@@ -52,6 +52,8 @@ The first arrangement mixer panel should be a UI shell and may keep fader, mute,
 
 Do not silently introduce persisted mixer semantics in a UI-only feature. When mixer routing is implemented, track and master mixer state should become serializable project data or serializable app-model data while runtime audio objects remain outside project JSON.
 
+The first functional mixer implementation keeps track mixer settings as app-model state keyed by `trackId`, with a separate master mixer state. This remains serializable and can move into the future persisted `Project` shape without storing Web Audio nodes.
+
 Recommended first mixer state:
 
 ```ts
@@ -69,6 +71,8 @@ export interface MasterMixerState {
 
 Default values should be `volumeDb: 0`, `muted: false`, `solo: false`, and master `volumeDb: 0`.
 
+The first fader range is `-60 dB` to `+6 dB`. `-60 dB` is treated as silent for practical gain calculation.
+
 Use a simple, testable solo rule:
 
 ```text

docs/features/17-mixer-audio-routing-and-track-controls.md

@@ -1,7 +1,7 @@
 # Feature: 17 Mixer Audio Routing and Track Controls
 
 ## Status
-Planned
+In Review
 
 ## Goal
 

docs/testing.md

@@ -29,6 +29,7 @@ CI uses `--if-present` while the repository is still before the Vite scaffold.
 - Tempo control and scheduler tempo update behavior: unit tests where practical.
 - Mixer decibel-to-gain conversion and mute/solo effective-gain logic: unit tests.
 - Mixer state transformations for volume, mute, solo, and master volume: unit tests.
+- Arrangement playback event expansion should preserve `trackId` so scheduled sources can route through the mixer.
 - Sustain loop point calculations: unit tests.
 - Sampler sustain metadata validation and fallback decisions: unit tests.
 - Scheduler calculations: unit tests where possible.

docs/ui-design.md

@@ -194,6 +194,8 @@ When playback is stopped, meters may settle to zero while faders and mute/solo s
 
 Effect slots should remain visibly disabled or placeholder-only until a dedicated effects feature implements real processing.
 
+The functional mixer should label its meters as live/runtime feedback and keep effect slots disabled. The master strip exposes master volume and meter feedback; track strips expose volume, mute, solo, and meter feedback.
+
 ## Component Naming Recommendations
 
 Prefer names that match the product domain:

src/app/App.tsx

@@ -5,6 +5,7 @@ import {
   createAudioEngine,
   expandClipInstancesForPlayback,
   type BundledSampleMeta,
+  type MixerLevelSnapshot,
   type NoteLoopEvent,
   type SampleLoopEvent,
 } from "../audio";
@@ -26,6 +27,8 @@ import {
   createClipInstance,
   createDefaultArrangementLoopRange,
   createDefaultArrangementTracks,
+  createDefaultMasterMixerState,
+  createDefaultTrackMixerStates,
   createImportedAudioClipDraft,
   createImportedAudioIds,
   createEmptyHybridClip,
@@ -43,8 +46,10 @@ import {
   renameClip,
   toggleDrumSubstep,
   validateImportedWavFile,
+  updateMasterMixerState,
   updateDrumLaneSample,
   updateDrumStepSubdivision,
+  updateTrackMixerState,
   type ArrangementLoopRange,
   type ArrangementTrack,
   type Clip,
@@ -53,9 +58,11 @@ import {
   type DrumLaneId,
   type DrumStepSubdivision,
   type HybridClip,
+  type MasterMixerState,
   type NoteEvent,
   type PitchedInstrumentId,
   type SampleMeta,
+  type TrackMixerState,
 } from "../model";
 import { DEFAULT_TEMPO_BPM, clampTempoBpm, type Tick } from "../utils";
 import styles from "./App.module.css";
@@ -87,6 +94,15 @@ function noteEventsToNoteLoopEvents(
   }));
 }
 
+function createEmptyMixerLevels(
+  tracks: readonly ArrangementTrack[],
+): MixerLevelSnapshot {
+  return {
+    masterLevel: 0,
+    trackLevels: Object.fromEntries(tracks.map((track) => [track.id, 0])),
+  };
+}
+
 function createNextHybridClip(clips: readonly Clip[]): HybridClip {
   const nextClipNumber =
     clips.reduce((highestClipNumber, clip) => {
@@ -114,6 +130,17 @@ export function App() {
   const [arrangementTracks] = useState<ArrangementTrack[]>(() =>
     createDefaultArrangementTracks(),
   );
+  const [trackMixerStates, setTrackMixerStates] = useState<TrackMixerState[]>(
+    () => createDefaultTrackMixerStates(arrangementTracks),
+  );
+  const trackMixerStatesRef = useRef<TrackMixerState[]>(trackMixerStates);
+  const [masterMixerState, setMasterMixerState] = useState<MasterMixerState>(() =>
+    createDefaultMasterMixerState(),
+  );
+  const masterMixerStateRef = useRef<MasterMixerState>(masterMixerState);
+  const [mixerLevels, setMixerLevels] = useState<MixerLevelSnapshot>(() =>
+    createEmptyMixerLevels(arrangementTracks),
+  );
   const [arrangementLoopRange, setArrangementLoopRange] =
     useState<ArrangementLoopRange>(() => createDefaultArrangementLoopRange());
   const arrangementLoopRangeRef =
@@ -175,6 +202,16 @@ export function App() {
     sampleMetasRef.current = sampleMetas;
   }, [sampleMetas]);
 
+  useEffect(() => {
+    trackMixerStatesRef.current = trackMixerStates;
+    audioEngine.setTrackMixerStates(trackMixerStates);
+  }, [trackMixerStates]);
+
+  useEffect(() => {
+    masterMixerStateRef.current = masterMixerState;
+    audioEngine.setMasterMixerState(masterMixerState);
+  }, [masterMixerState]);
+
   useEffect(() => {
     return () => {
       audioEngine.stopCachedSamplePreview();
@@ -203,6 +240,26 @@ export function App() {
     };
   }, [transportState]);
 
+  useEffect(() => {
+    if (transportMode !== "song" || transportState !== "playing") {
+      return;
+    }
+
+    let animationFrameId = 0;
+    const trackIds = arrangementTracks.map((track) => track.id);
+
+    function updateMixerLevels() {
+      setMixerLevels(audioEngine.getMixerLevels(trackIds));
+      animationFrameId = window.requestAnimationFrame(updateMixerLevels);
+    }
+
+    animationFrameId = window.requestAnimationFrame(updateMixerLevels);
+
+    return () => {
+      window.cancelAnimationFrame(animationFrameId);
+    };
+  }, [arrangementTracks, transportMode, transportState]);
+
   function commitSelectedClip(nextClip: HybridClip) {
     const nextClips = clipsRef.current.map((clip) =>
       clip.id === nextClip.id ? nextClip : clip,
@@ -298,6 +355,42 @@ export function App() {
     setArrangementLoopRange(normalizedLoopRange);
   }
 
+  function handleTrackVolumeChange(trackId: string, volumeDb: number) {
+    setTrackMixerStates((currentStates) =>
+      updateTrackMixerState(currentStates, trackId, { volumeDb }),
+    );
+  }
+
+  function handleTrackMuteToggle(trackId: string) {
+    setTrackMixerStates((currentStates) => {
+      const currentState = currentStates.find(
+        (state) => state.trackId === trackId,
+      );
+
+      return updateTrackMixerState(currentStates, trackId, {
+        muted: !(currentState?.muted ?? false),
+      });
+    });
+  }
+
+  function handleTrackSoloToggle(trackId: string) {
+    setTrackMixerStates((currentStates) => {
+      const currentState = currentStates.find(
+        (state) => state.trackId === trackId,
+      );
+
+      return updateTrackMixerState(currentStates, trackId, {
+        solo: !(currentState?.solo ?? false),
+      });
+    });
+  }
+
+  function handleMasterVolumeChange(volumeDb: number) {
+    setMasterMixerState((currentState) =>
+      updateMasterMixerState(currentState, { volumeDb }),
+    );
+  }
+
   function getSelectedHybridClip(): HybridClip | null {
     const clip = selectedClipRef.current;
 
@@ -860,6 +953,7 @@ export function App() {
     }
 
     stopAudioClipPreview();
+    setMixerLevels(createEmptyMixerLevels(arrangementTracks));
 
     if (transportState !== "stopped") {
       const snapshot = audioEngine.stopLoop();
@@ -883,6 +977,7 @@ export function App() {
     } catch (error) {
       setTransportState("stopped");
       commitPlayheadTick(audioEngine.stopLoop().currentTick);
+      setMixerLevels(createEmptyMixerLevels(arrangementTracks));
       setAudioError(
         error instanceof Error ? error.message : "Arrangement playback failed.",
       );
@@ -917,6 +1012,9 @@ export function App() {
       clips: clipsRef.current,
     });
 
+    audioEngine.setTrackMixerStates(trackMixerStatesRef.current);
+    audioEngine.setMasterMixerState(masterMixerStateRef.current);
+
     return audioEngine.startClipLoop({
       loopEndTick: normalizedLoopRange.endTick,
       loopStartTick: normalizedLoopRange.startTick,
@@ -1017,6 +1115,7 @@ export function App() {
       const snapshot = audioEngine.stopLoop();
       setTransportState(snapshot.status);
       commitPlayheadTick(snapshot.currentTick);
+      setMixerLevels(createEmptyMixerLevels(arrangementTracks));
       return;
     }
 
@@ -1025,6 +1124,7 @@ export function App() {
       const snapshot = audioEngine.pauseLoop();
       setTransportState(snapshot.status);
       commitPlayheadTick(snapshot.currentTick);
+      setMixerLevels(createEmptyMixerLevels(arrangementTracks));
       return;
     }
 
@@ -1129,9 +1229,16 @@ export function App() {
               onClipInstanceMove={handleClipInstanceMove}
               onClipInstanceSelect={setSelectedClipInstanceId}
               onLoopRangeChange={handleArrangementLoopRangeChange}
+              onMasterVolumeChange={handleMasterVolumeChange}
+              onTrackMuteToggle={handleTrackMuteToggle}
+              onTrackSoloToggle={handleTrackSoloToggle}
+              onTrackVolumeChange={handleTrackVolumeChange}
               playheadTick={playheadTick}
+              masterMixerState={masterMixerState}
+              mixerLevels={mixerLevels}
               selectedClipInstanceId={selectedClipInstanceId}
               shouldShowPlayhead={shouldShowPlayhead}
+              trackMixerStates={trackMixerStates}
               tracks={arrangementTracks}
             />
           ) : selectedAudioClip ? (

src/audio/arrangement-events.ts

@@ -38,6 +38,7 @@ export function expandClipInstancesForPlayback({
           id: `${instance.id}:audio`,
           sampleId: clip.sampleId,
           startTick: instance.startTick,
+          trackId: instance.trackId,
         });
       }
 
@@ -58,6 +59,7 @@ export function expandClipInstancesForPlayback({
         id: `${instance.id}:${event.id}`,
         sampleId: event.sampleId,
         startTick: instance.startTick + event.startTick,
+        trackId: instance.trackId,
       });
     }
 
@@ -73,6 +75,7 @@ export function expandClipInstancesForPlayback({
         instrumentId: event.instrumentId,
         midiNote: event.midiNote,
         startTick: instance.startTick + event.startTick,
+        trackId: instance.trackId,
       });
     }
   }