Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
description: "Task list for 009 Undo for Volume and Pan"
Tasks: Undo for Volume and Pan
Input: Design documents from /specs/009-mix-param-undo/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md
Tests: Requested — FR-013 lists the smoke-test coverage, and the constitution (IV)
requires it for an engine behaviour change. Engine-level tests live in one new file,
tests/Nota.SmokeTest/MixUndoTests.cs, so tasks touching it are sequential.
Organization: by user story — US1 take back a move (P1), US2 one history (P1), US4 non-edits stay out (P1), US3 every source (P2).
Format: [ID] [P?] [Story] Description
- [P]: Can run in parallel (different files, no dependencies on incomplete tasks)
- [Story]: US1 / US2 / US3 / US4
Phase 1: Setup
- T001 Run
scripts/build.shon the untouched tree and confirm it is green (baseline); if red, stop and report
Phase 2: Foundational (Blocking Prerequisites)
Purpose: the history can hold mix steps and the gesture API exists end to end. No source is wired yet, so the app behaves as before.
⚠️ CRITICAL: No user story work can begin until this phase is complete
- T002 In
src/native/nota.engine/src/Engine.haddenum class MixKind : int32_t { TrackVolume = 0, TrackPan = 1, MasterVolume = 2 };,struct MixChange { MixKind kind; int32_t trackId; float before; float after; };andstruct UndoEntry { std::shared_ptr<Graph> graph; std::vector<MixChange> mix; };("graph: the state to restore; null for a mix-only step"; "mix: empty for a structural step; at most one change per target"), changeundoStack_/redoStack_tostd::vector<UndoEntry>, and adduint64_t undoPushCount_ = 0; - T003 In
src/native/nota.engine/src/Engine.cppadapt the history toUndoEntry:pushUndo()pushes{authoring_, {}}and incrementsundoPushCount_;undo()pops an entry, pushes{graph ? authoring_ : nullptr, mix}onto redo,publishRaw(graph)when it has one, then applies every change'sbefore(track volume/pan via the authoring track's setter, skipping a missing track; master volume via the master setter) — if the entry has no graph and applied nothing, continue with the next entry (research R3);redo()symmetric withafter;endUndoGroup()merges the dropped entries'mixinto the kept first entry (same target → keep the olderbefore, the newerafter; drop a target whose mergedbefore == after);canUndo/canRedo/clearUndoHistorykeep working; update the undo comment block inEngine.h("volume, pan and master volume steps from mix gestures are covered; mute, solo, sends, device params and the transport are not") - T004 In
Engine.h/Engine.cppadd the gesture API (research R2, data-model § Open gesture):int32_t beginMixGesture(const MixTarget* targets, int32_t count)(records each valid target's current value asbeforeandpushCountAtBegin = undoPushCount_; returns a handle > 0, or 0 if no target is valid),void endMixGesture(int32_t handle)(unknown handle → no-op; builds changes with exact float compare, dropping unchanged targets and vanished tracks; none → return; ifundoPushCount_ != pushCountAtBeginand the undo stack is not empty → merge intoundoStack_.back()by the merge rule; else push{nullptr, changes}, trim tokMaxUndoDepth, clear redo),float masterVolume() const;reset()andclearUndoHistory()drop all open gestures. Message thread only, no audio-thread code - T005 Add the C ABI from contracts/c-abi-mix-undo.md verbatim to
src/native/nota.engine/include/nota/nota_engine.h(NOTA_MIX_*,NotaMixTarget,nota_mix_gesture_begin,nota_mix_gesture_end,nota_engine_master_volume, updated undo comment) and implement it insrc/native/nota.engine/src/nota_engine_core.cpp(null engine → 0 / no-op / 1.0f) - T006 [P] In
src/managed/Nota.Application/Engine/EngineContracts.csaddpublic enum MixKind { TrackVolume = 0, TrackPan = 1, MasterVolume = 2 }and[StructLayout(LayoutKind.Sequential)] public readonly record struct MixTarget(MixKind Kind, int TrackId)with static helpersVolume(id),Pan(id),Master; insrc/managed/Nota.Application/Engine/IAudioEngine.csaddint BeginMixGesture(params MixTarget[] targets),void EndMixGesture(int handle),float MasterVolume { get; } - T007 [P] P/Invokes in
src/managed/Nota.Infrastructure/Interop/NativeMethods.cs(MixGestureBegin(IntPtr, MixTarget[], int),MixGestureEnd(IntPtr, int),MasterVolume(IntPtr)) and wrappers insrc/managed/Nota.Infrastructure/Interop/NotaEngine.cs - T008 [P] Create
src/managed/Nota.Application/Editing/MixEdit.cs(SPDX header; file comment: one-shot undoable volume/pan edits, specs/009) withpublic static void Step(IAudioEngine engine, Action set, params MixTarget[] targets)— begin, runset, end (end runs even ifsetthrows) - T009 Create
src/managed/Nota.App/MixGestureWiring.cs(SPDX header) per contracts/sources.md:Wire(IAudioEngine engine, Action<Action> onBegin, Action<Action> onEnd, Action<Action<double>> onValue, Func<MixTarget[]> targets)style helper (adapt the signature to the controls' events) —GestureBegin→ open a handle,GestureEnd→ end it, a value change while no handle is open → one-shot viaMixEdit.Step; andDebouncedMixGesture(DispatcherTimer, configurable pause, default 1 s) whoseTouch()opens a gesture if none is open and restarts the timer, ending the gesture when it fires - T010 Create
tests/Nota.SmokeTest/MixUndoTests.cs(SPDX header; comment "Undo for volume and pan (specs/009-mix-param-undo); also--mixundo") withRun()and wire it intests/Nota.SmokeTest/Program.cs(full run next toPanLawTests, plus a--mixundobranch like--panlaw); first checks: begin(vol t) · 50 sets · end · undo → exactly the begin value, redo → exactly the last value; begin · end with no set →CanUndounchanged; set back to the start value → no step; master gesture →MasterVolumerestored;Reset()with an open gesture thenEndMixGesture→ no step
Checkpoint: scripts/build.sh green; the engine API works; no source wired yet.
Phase 3: User Story 1 — Take back a fader move (Priority: P1) 🎯 MVP
Goal: fader/knob drags, resets and typed values in the Mixer, the track headers and the Return/Master rows are one undo step each.
Independent Test: quickstart § 2 steps 1–2.
- T011 [US1] In
src/managed/Nota.App/MixerView.cswire withMixGestureWiring:PanRowknob (target pan),FaderRowVFaderand the dBDragNumber(target volume) — keep the existingBeginAutomationWrite/EndAutomationWritecalls, opening the mix gesture before the automation write and ending it after; the master strip fader (targetMixTarget.Master); double-click resets and typed dB values arrive with no gesture open → one-shot - T012 [US1] In
src/managed/Nota.App/ArrangementView.cswire the header mini fader and pan bar (lines 1848–1862, same ordering with the automation write) and the Return/Master footer rows (2425–2466; the master row targetsMixTarget.Master) - T013 [US1] In
src/managed/Nota.App/MainWindow.Menu.csRefreshAfterUndoRedo(): setvm.Transport.MasterVolume = Engine.MasterVolumewhen it differs (research R4) so MST, the Master strip and the Master row follow an undo; check the MSTMiniFaderinMainWindow.axaml.cs(~line 223) followsvm.Transport.MasterVolumechanges — if it does not, make it follow (skip while dragging) - T014 [US1] Headless UI check (memory "Nota UI verify recipe",
NOTA_DATA_DIR): drive a Mixer fader drag, a pan knob drag, a double-click reset and a typed dB value with synthetic events; after each,Undo()restores the exact value in the engine and in the fader/dB field,Redo()re-applies; record results in the PR, not in code
Checkpoint: US1 works in the Mixer, headers and Return/Master rows.
Phase 4: User Story 2 — One history for everything (Priority: P1)
Goal: mix steps and structural steps share one strictly ordered history.
Independent Test: contract Guarantees rows on ordering and deleted tracks.
- T015 [US2] In
tests/Nota.SmokeTest/MixUndoTests.cs: add track · volume gesture ·SetPanLaw(Stereo)· pan gesture · undo ×4 → each intermediate state matches in reverse order; redo ×4 forward; a new edit after two undos drops redo - T016 [US2] In
tests/Nota.SmokeTest/MixUndoTests.cs: begin(vol t) · set ·RemoveTrack(t)· end → no mix step (the removal is the top step); volume gesture on t · remove t · undo · undo → t back, then its volume back; two gestures open at once on different tracks → two steps in end order; an undo group (BeginUndoGroup/EndUndoGroup) containing two volume gestures on the same track → one step from the firstbeforeto the lastafter - T017 [US2] Fix whatever T015–T016 expose in
src/native/nota.engine/src/Engine.cpp(ordering, merge, skip) until they pass
Checkpoint: ordering guarantees hold.
Phase 5: User Story 4 — Things that are not edits stay out (Priority: P1)
Goal: automation playback, loads, the template and freeze make no steps; automation recording merges with its gesture.
Independent Test: quickstart § 2 steps 4–5; contract rows on automation.
- T018 [US4] In
tests/Nota.SmokeTest/MixUndoTests.cs: a volume + pan automation lane in read mode, clear history, render 2 s while playing →CanUndo == false;ProjectTemplate.ApplyDefaultand a project save → load →CanUndo == falsefor mix steps (no volume/pan values change on undo);TrackFreezer.Freezeon a track → undo does not touch its volume - T019 [US4] In
tests/Nota.SmokeTest/MixUndoTests.cs:SetAutomationRecord(true)·BeginMixGesture(vol t)·BeginAutomationWrite· sets while rendering ·EndAutomationWrite·EndMixGesture· oneUndo()→ both the lane points and the volume are back; oneRedo()→ both again (FR-009) - T020 [US4] Confirm (grep) that
ProjectService.Apply,ProjectTemplate,MainWindow.Freeze.cs,MainWindow.LiveFreeze.csandMainWindow.Files.csresets use only the plain setters, neverBeginMixGesture/MixEdit.Step; fix any that do
Checkpoint: non-edits make no steps; recording merges.
Phase 6: User Story 3 — Every way of mixing is undoable (Priority: P2)
Goal: Session mixer, MST, Remote, MIDI Learn and MCP changes are undoable.
Independent Test: one change from each source, undo each.
- T021 [P] [US3] In
src/managed/Nota.App/SessionView.Mixer.cswire the pan knob (line 117) and the volume fader (126) withMixGestureWiring(sends stay unwired — out of scope) - T022 [P] [US3] In
src/managed/Nota.App/MainWindow.axaml.cswire the MSTMiniFader(~line 223) toMixTarget.MasterviaMixGestureWiring - T023 [P] [US3] In
src/managed/Nota.Remote/RemoteHub.Apply.cs(vol,pan,mvol): keep a per-client map(kind, id) → handle; open a gesture on the first command of a touch when none is open, end it whencmd.Phase == 2, and end any open handles when the client disconnects - T024 [P] [US3] In
src/managed/Nota.App/MidiLearnService.cs(~lines 348–350): routeTrackVolume,TrackPan,MasterVolumethrough oneDebouncedMixGestureper mapping (1 s pause) - T025 [P] [US3] In
src/managed/Nota.Mcp/Tools/TrackTools.cswrapset_track_volumeandset_track_panbodies inMixEdit.Step(inside the existingMutate) - T026 [US3] In
tests/Nota.SmokeTest/MixUndoTests.cs:TrackTools.SetTrackVolumethroughMcpTestSupport(SyncDispatch,NoRefresh) is one undo step; the Remotevolcommand sequence phase 0 → 1 → 2 through the hub (or its apply method) is one step
Checkpoint: every listed source is undoable.
Phase 7: Polish & Cross-Cutting Concerns
- T027 Headless UI pass of quickstart § 2 (steps 3–5: MST, automation playback, recording merge) in both themes; nothing visual changes, so no screenshots needed beyond confirmation
- T028 [P] Performance sanity: a 2 s fader drag (≈120 value changes) allocates nothing per change on the managed side beyond today's (values are only read at begin/end); note it in the PR
Nota closing tasks
- T029 Run
scripts/build.shuntil native + managed + smoke test are green - T030 AGPL-3.0-only SPDX header on every new source file (
MixEdit.cs,MixGestureWiring.cs,MixUndoTests.cs) - T031 New dependency: N/A
- T032
CHANGELOG.md[Unreleased]Added: "Undo for volume and pan: fader, pan and master-volume moves can be undone and redone (⌘Z / ⌘⇧Z) from the Mixer, track headers, Session mixer, transport, Nota Remote, a MIDI controller and the AI assistant; one move is one step. Automation playback never adds steps." - T033 FEATURES.md via
nota-features(Project and transport: what undo covers); user docs EN + RU vianota-docs(the page that describes undo); shortcuts: N/A - T034 Engine behaviour change → smoke test extended: confirm all
MixUndoTestslabels pass in the full run and with--mixundo
Dependencies & Execution Order
- Setup (T001) → Foundational (T002–T010) → stories → Polish (T027–T034)
- T002 → T003 → T004 → T005 → (T006 ∥ T007) → T008 → T009; T010 after T007
- US1 (T011–T014), US2 (T015–T017), US4 (T018–T020) depend only on Foundational
- US3 (T021–T026) depends on Foundational (T009 for the wiring helper)
- Tests in
MixUndoTests.csare sequential: T010 → T015 → T016 → T018 → T019 → T026
Parallel Opportunities
- T006 ∥ T007 (Application vs Infrastructure)
- T021 ∥ T022 ∥ T023 ∥ T024 ∥ T025 (five different files)
- US1 wiring (App) alongside US2 test work (smoke test) once Foundational is done
Parallel Example: User Story 3
Task: "T021 Session mixer wiring in src/managed/Nota.App/SessionView.Mixer.cs"
Task: "T022 MST wiring in src/managed/Nota.App/MainWindow.axaml.cs"
Task: "T023 Remote gestures in src/managed/Nota.Remote/RemoteHub.Apply.cs"
Task: "T024 MIDI Learn debounce in src/managed/Nota.App/MidiLearnService.cs"
Task: "T025 MCP one-shot in src/managed/Nota.Mcp/Tools/TrackTools.cs"
Implementation Strategy
MVP
Foundational + US1 + US2 + US4 is the minimum shippable: the Mixer and headers become undoable without corrupting the history or flooding it during playback. US3 completes the spec's promise of every source (FR-007); ship all four together in one PR — a partial set would make undo behave differently depending on where the user moved a fader.
Incremental order
- T001–T010 → engine + API, build green, no visible change
- US1 → Mixer / headers / Return-Master undoable
- US2 → ordering verified
- US4 → playback/loads excluded, recording merges
- US3 → Session, MST, Remote, MIDI, MCP
- Polish → UI pass, docs, final build
Notes
- Do not commit or push — the user reviews and commits.
.specify/feature.jsonpoints atspecs/007-midi-note-editing; run spec-kit scripts for this feature withSPECIFY_FEATURE_DIRECTORY=specs/009-mix-param-undo SPECIFY_FEATURE_NO_PERSIST=1.- Spec 008 (Stereo Map) waits for this one: a map drag is one gesture with two targets.
Phase 8: Convergence
- T035 Reconcile the scroll-wheel rule (US1 scenario 5, FR-003 "a burst of scroll-wheel notches…"): no volume/pan control handles the wheel today, so either drop the scenario from the spec via
/speckit-clarifyor add wheel support toPanKnob,VFader,MiniFader,PanBar(src/managed/Nota.App/Controls/) driven through a 0.5 sDebouncedMixGestureper control per US1/AC5 (partial) - T036 Add an engine self-test (pattern of the existing
*SelfTestfunctions insrc/native/nota.engine/src/, exposed throughnota_engine.hand called fromtests/Nota.SmokeTest/MixUndoTests.cs) that pushes a mix-only undo entry for a track id not in the graph above a valid step and checks that oneundo()skips it and undoes the valid step, andredo()mirrors it, per FR-010 / FR-013 (partial) - T037 Make the MIDI-controller pause testable without a UI timer — let
DebouncedMixGesture(src/managed/Nota.App/MixGestureWiring.cs) take the pause timer through a small abstraction, or move the debounce logic intoNota.Applicationwith an injected clock — and add a smoke-test check that two movements separated by more than the pause are two steps and a continuous one is one, per US3 scenario 3 / quickstart § 1 (partial) - T038 Remove the per-move closure allocation in the wired controls (
src/managed/Nota.App/MixerView.cs,ArrangementView.cs,SessionView.Mixer.cs,MainWindow.axaml.cs): when the control'sMixGestureis open call the setter directly and only fall back toChange(...)for one-off values, or record inplan.mdPerformance Goals that one small closure per move is accepted, per plan: Performance Goals (partial)