first commit

docs/media/audio/audio-timeline/src/engine/mixer/mixer.md

@@ -0,0 +1,35 @@
+# Engine Mixer Helpers
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `mixer.ts` module bridges `TimelineEngine` mixer public methods to the pure `mixer.ts` helpers. It manages undo pushes and adapter forwarding for every mixer mutation, keeping the engine class from growing too large.
+
+## Features
+
+- `engineSetMasterVolume` updates master volume and pushes undo
+- `engineSetTrackVolume` delegates to pure helper and forwards to adapter
+- `engineSetTrackMute` toggles mute and emits via adapter
+- `engineSetTrackSolo` toggles solo and emits via adapter
+- `engineSetTrackPan` clamps pan and emits via adapter
+
+## Usage
+
+These helpers are used internally by `TimelineEngine`. Consumers call `engine.setTrackVolume(id, 0.8)` etc.
+
+## API Reference
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `engineSetMasterVolume` | `(deps, volume) => void` | Master volume |
+| `engineSetTrackVolume` | `(deps, trackId, volume) => void` | Track volume |
+| `engineSetTrackMute` | `(deps, trackId, muted) => void` | Track mute |
+| `engineSetTrackSolo` | `(deps, trackId, soloed) => void` | Track solo |
+| `engineSetTrackPan` | `(deps, trackId, pan) => void` | Track pan |
+
+## Implementation Notes
+
+The `MixerDeps` interface isolates the helpers from the engine class. Every track mutation goes through `updateTrackInPlace`, which pushes an undo command automatically. The master volume operation is special-cased because it does not live on a track; it pushes its own undo command directly. All other mixer state lives on individual tracks and is therefore covered by the standard track-update undo path. This symmetry makes it easy to reason about what changes are reversible.