Mixer audio routing and track controls

[britle20]

Feature Spec

Related feature document: docs/features/17-mixer-audio-routing-and-track-controls.md

Goal

Connect the existing SONG mixer panel to real audio behavior: per-track routing, volume, mute, solo, master volume, and runtime level meters.

Context

The arrangement mixer panel currently establishes the UI shell only. It has faders, mute/solo buttons, level meters, effect-slot placeholders, and a master strip, but those controls do not affect Web Audio playback.

This feature should make the mixer useful for arrangement playback without turning it into a full mixer/effects system.

Scope

Included:

• Add serializable mixer state for tracks and the master output.
• Route arrangement playback sources through track gain nodes and then a master gain node.
• Make track volume faders control real track gain.
• Make the master fader control real master gain.
• Make mute and solo buttons affect actual track audibility.
• Add runtime level metering for track channels and master output where practical.
• Keep meter signal data and Web Audio nodes runtime-only.
• Keep existing mixer panel visual structure and CSS Modules styling.
• Add focused tests for mixer state transformations, dB-to-gain conversion, and mute/solo effective-gain logic.
• Update architecture, data model, audio engine, UI, and testing docs.

Excluded:

• Audio effects or effect chain processing.
• Mixer automation.
• Pan, sends, buses, sidechain routing, or recording arm.
• Offline export or render-to-file behavior.
• Persisted project export/import beyond serializable state shape.
• Reworking the visual mixer shell beyond what is needed to wire controls.
• Adding runtime dependencies.

Constraints

• This feature depends on arrangement playback having track-aware scheduled sources.
• React UI must not own exact audio timing.
• Web Audio nodes, analyser nodes, meter buffers, and routing graph objects are runtime-only.
• Project data may store mixer settings such as volume, mute, and solo, but not runtime audio objects.
• Use CSS Modules and semantic design tokens.
• Keep effect slots visually present as placeholders unless a later feature implements actual effects.

Done when

• Arrangement playback routes each track through a track mixer channel.
• Track volume faders change audible level during playback.
• Master volume changes overall output level during playback.
• Muting a track makes that track silent.
• Soloing one or more tracks makes only audible soloed tracks play, with muted soloed tracks still silent.
• Track and master meters display runtime audio levels when playback is active.
• Stopping playback clears or decays visible meter levels without stuck values.
• Mixer settings are represented as serializable state where appropriate.
• Runtime Web Audio graph objects are not stored in project JSON.
• Existing PAT mode playback still works.
• Relevant tests and docs are updated.

Verification

Run:

• npm run typecheck
• npm run lint
• npm run test
• npm run build

Manual check:

• Place clips on multiple arrangement tracks.
• Start SONG playback.
• Move a track fader and confirm only that track changes level.
• Move the master fader and confirm overall output changes.
• Mute a track and confirm it becomes silent.
• Solo one track and confirm non-solo tracks become silent.
• Solo multiple tracks and confirm only those tracks remain audible.
• Confirm meters respond to playback and settle after stop.
• Confirm PAT mode playback still works.

Notes

Actual audio effects should remain a separate feature after the routing path is stable.

[britle20]

Implemented by PR #52, merged into develop.