Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
Feature Specification: Undo for Volume and Pan
Feature Branch: 009-mix-param-undo
Created: 2026-10-14
Status: Draft
Clarifications
Session 2026-10-14
- Q: Should sends, mute and solo become undoable in the same change? → A: No — volume and pan only (plus the master volume); sends, mute and solo can follow in a later spec on the same mechanism.
- Q: How should continuous MIDI-controller movement be grouped into undo steps? → A: One step per movement, ended by a 1 s pause in that control's messages.
Session 2026-10-14 (convergence)
- Q: The spec asks for scroll-wheel bursts to be one step, but no volume/pan control reacts to the wheel. Add wheel support or drop the rule? → A: Drop it — wheel control of faders is a feature of its own; when it arrives it uses the same pause-based gesture.
Input: User description: "Undo for volume and pan, everywhere (prerequisite of specs/008-stereo-map, clarified 2026-10-14 option C). Today track/return volume and pan (and the master volume) are not undoable anywhere in Nota. Make every user change of a track's or return's volume or pan, and of the master volume, undoable and redoable with ⌘Z / ⌘⇧Z, interleaved in one history with all other edits. One gesture = one step: a fader/knob drag from press to release; a double-click reset; a typed or dragged dB value; a scroll-wheel burst; a Stereo Map drag (pan + volume together, one step). Sources: Mixer strips, track headers, Return/Master rows, Session mixer, the transport MST, MIDI controller via MIDI Learn, Nota Remote, MCP tools. Never an undo step: automation playback, project load, freeze/live-freeze internals, the new-project template. While recording automation, the lane edit and the value change undo together. Undo restores the exact previous value and every view follows."
Nota Context (fill in — drives plan and tasks)
Feature area (pick the main one):
- Engine (C++,
src/native/nota.engine) — real-time audio rules apply, seeARCHITECTURE.mdAR table - Managed app (C#,
src/managed/*) — domain, application, infrastructure, presentation — plus the engine's undo history, which today covers structural edits only - UI (Avalonia,
src/managed/Nota.Presentation) — followDESIGN.md(Ember) - Plugin hosting (
pluginhost/) — the only place JUCE is allowed - Build / packaging / CI (
scripts/,.github/) — seeBUILD.md - Docs only
Nota docs to keep in mind (links relative to specs/<slug>/, where this file lands):
ARCHITECTURE.md (AR rules),
CONTRIBUTING.md (licensing, dependency policy, PR
expectations), BUILD.md, DESIGN.md,
FEATURES.md.
Current state (for reference):
- One history (⌘Z / ⌘⇧Z, Edit menu, the command palette's undo) covers structural edits: tracks, clips, notes, device chains, session slots, automation lanes, the pan law. It explicitly does not cover volume, pan, mute, solo, sends, device parameters or the transport.
- Volume and pan of tracks and returns, and the master volume, are changed from: the Mixer
window (knob, fader, dB field — typed or dragged), the arrangement track headers (pan bar,
mini fader), the Return and Master rows under the tracks, the Session-view mixer, the
transport's MST control, a MIDI controller mapped with MIDI Learn, Nota Remote (phone),
and the MCP tools
set_track_volume/set_track_pan(AI control). - Internal operations also set them: project load, freeze / live freeze, the new-project template, automation playback.
- Prerequisite of the Stereo Map (specs/008), which requires a map drag to be one undo step.
User Scenarios & Testing (mandatory)
User Story 1 - Take back a fader move (Priority: P1)
A producer drags the vocal fader up by 6 dB, listens, and does not like it. ⌘Z puts the fader back exactly where it was; ⌘⇧Z brings the 6 dB back. The same works for a pan knob, a double-click reset and a value typed into the dB field.
Why this priority: The basic expectation of any DAW; today a slip on a fader cannot be taken back at all.
Independent Test: In the Mixer, drag a fader, turn a pan knob, reset one with a double-click and type a dB value; undo each and redo each.
Acceptance Scenarios:
- Given a track at 0 dB, When the user drags its fader to +6 dB in one press and release and presses ⌘Z, Then it is back at exactly 0 dB, and ⌘⇧Z returns it to +6 dB.
- Given a pan knob at C, When the user turns it to L40 and presses ⌘Z, Then it is at C again.
- Given a track at −8 dB, When the user double-clicks its fader (reset to 0 dB) and presses ⌘Z, Then it is at −8 dB again.
- Given the dB field, When the user types −12 and confirms, Then that is one undo step; When they drag the dB number, Then the whole drag is one step.
User Story 2 - One history for everything (Priority: P1)
The producer adds a track, moves the bass fader, switches the pan law to Stereo, pans the guitar, then presses ⌘Z four times: the guitar pan, the pan law, the bass fader and the new track come back one by one, in reverse order. Every view — Mixer, track headers, Remote, Stereo Map — shows the restored values.
Why this priority: Undo that skips some edits or jumps out of order is worse than no undo; mixing and structural edits must share one timeline.
Independent Test: Alternate structural edits and volume/pan edits, undo and redo the whole chain and check each intermediate state.
Acceptance Scenarios:
- Given a sequence of edits mixing structure, pan law and volume/pan, When the user undoes repeatedly, Then each step reverts exactly the most recent remaining edit, in reverse order, and redo replays them in order.
- Given a new edit after some undos, When it is made, Then the redo history is dropped (as for any edit today).
- Given an undone volume change, When the user looks at the Mixer, the track header, the Session mixer and a connected phone, Then they all show the restored value.
- Given a track deleted after its volume was changed, When the user undoes the delete and then the volume change, Then both come back correctly.
User Story 3 - Every way of mixing is undoable (Priority: P2)
The producer moves a volume from the Session mixer, a pan from a track header, the master from the transport's MST, a fader from Nota Remote on the phone, a knob on a MIDI controller, and asks the AI assistant (MCP) to set a level. Each of those is undoable from the computer.
Why this priority: Consistency across sources; the main sources (US1) already give most of the value.
Independent Test: Change volume/pan once from each source and undo each.
Acceptance Scenarios:
- Given each source listed in Current state, When the user changes a volume or pan with it, Then ⌘Z reverts that change.
- Given a touch on Nota Remote, When the finger moves a fader and lifts, Then the whole touch is one step.
- Given a MIDI controller knob turned continuously, When the user stops turning, Then the movement up to a 1 s pause in that control's messages is one step; turning it again after the pause starts a new step.
- Given an MCP call that sets a volume, When it completes, Then it is one step.
User Story 4 - Things that are not edits stay out of the history (Priority: P1)
While a song with volume automation plays, the faders move by themselves — that never fills the undo history. Opening a project, freezing a track or starting a new project does not leave undoable volume steps behind either.
Why this priority: Without it a playing song would flood the history and undo would become useless.
Independent Test: Play a song with volume and pan automation for a minute, freeze a track, open a project; the history gains no volume/pan steps.
Acceptance Scenarios:
- Given automation in read mode, When the song plays, Then no undo steps appear.
- Given a project is opened or a new project created, When the user presses ⌘Z, Then nothing about volume or pan is undone (there is nothing to undo).
- Given a freeze or live freeze, When it completes, Then any internal volume changes it made leave no undo step of their own.
- Given automation recording (write/touch/latch), When the user moves a fader in one gesture, Then ⌘Z reverts the recorded automation and the value together, one step.
Edge Cases
- Undo during playback: the value jumps back immediately; with automation in read mode on that parameter, the automation keeps winning, as it does for a manual move today.
- A gesture with no net change (press and release without moving, or a drag back to the start value): no undo step.
- Gesture interrupted (window loses focus, track deleted mid-drag): the change so far is one step; nothing is left half-open.
- Two sources at once (mouse on the fader while the phone moves the same fader): each gesture is its own step, in the order they finished.
- The master volume shares the history with track edits even though it is shown in the transport.
- Undo a volume change of a track that no longer exists (deleted, not undone): that step is skipped quietly; the next step is undone instead.
- Group tracks: their volume and pan are covered like any track's.
- History depth: volume/pan steps count against the existing history limit like any other step.
Requirements (mandatory)
Functional Requirements
- FR-001: Every user change of a track's, return's or group's volume or pan, and of the master volume, MUST be undoable and redoable through the existing history (⌘Z / ⌘⇧Z, Edit menu, command palette).
- FR-002: These steps MUST share one ordered history with all existing undoable edits; undo and redo MUST always act on the most recent step, whatever its kind.
- FR-003: One gesture MUST be exactly one step: a mouse drag from press to release; a double-click reset; a confirmed typed value; a drag of a dB number; one touch on Nota Remote from finger-down to lift; one MIDI-controller movement ended by a 1 s pause; one MCP call; a Stereo Map drag (its pan and volume together).
- FR-004: A step MUST restore the exact value from before the gesture (no rounding) and redo the exact value after it.
- FR-005: A gesture that ends at its starting value MUST NOT add a step.
- FR-006: All views and connected devices (Mixer, track headers, Return/Master rows, Session mixer, transport MST, Nota Remote, Stereo Map) MUST show the restored value at once.
- FR-007: The sources MUST all be covered: Mixer window, track headers, Return/Master rows, Session mixer, transport MST, Nota Remote, MCP, and a MIDI controller through MIDI Learn (grouping per US3 scenario 3).
- FR-008: Automation playback, project load, a new project, freeze / live freeze and any other internal setting of volume or pan MUST NOT create steps.
- FR-009: While recording automation, one gesture's lane edit and value change MUST undo and redo together as one step.
- FR-010: A step whose track no longer exists MUST be skipped without error.
- FR-011: Undo/redo of volume and pan MUST be click-free during playback no worse than moving the same control by hand.
- FR-012: The scope is volume and pan (tracks, returns, groups) and the master volume only; sends, mute and solo stay out of the history, as today.
- FR-013: The automated smoke test MUST cover: a drag-like change (begin, many values, end) is one step and restores exactly; a no-change gesture adds no step; volume/pan steps interleave in order with structural edits and the pan law switch; automation playback adds no steps; a step for a deleted track is skipped; MCP set_track_volume is one step.
- FR-014: The change MUST be listed in the changelog, FEATURES.md and the user docs (EN + RU) where undo is described.
Key Entities
- Mix step (one undo step): which parameter (track id + volume or pan, or master volume), the value before and the value after; a Stereo Map step carries two parameters.
- Gesture: a begin–end span from one source in which value changes merge into one step.
Success Criteria (mandatory)
Measurable Outcomes
- SC-001: 100 % of volume/pan changes made by the user from any listed source can be undone and redone, landing on the exact previous value.
- SC-002: Playing a song with volume and pan automation for 10 minutes adds 0 undo steps.
- SC-003: Undo/redo of a volume/pan step takes effect within one screen refresh in every open view.
- SC-004: A mixed sequence of 50 structural and volume/pan edits undoes and redoes in exactly the reverse/forward order, every intermediate state matching.
Assumptions
- Group tracks are covered like tracks; the master volume is covered although the history never covered the transport before (it is a fader the user mixes with).
- Undo steps have no labels (Nota's history has none; specs/006 clarification).
- MCP calls run one at a time; each call is one step.
- History depth stays as it is today; mix steps count toward it.
- Device parameters, sends, mute, solo, arm, tempo and the other transport values are out of scope (clarified).
- Volume/pan controls have no scroll-wheel input; wheel bursts are out of scope (clarified).
Nota Compliance Checklist (review before implementation; re-check in tasks.md)
- Every new source file will carry the AGPL-3.0-only SPDX header (two lines, see CONTRIBUTING.md)
- No new dependency — or: license checked, AGPL-compatible,
LICENSES/third-party.mdrow planned - Audio-thread impact considered: no alloc / lock / I/O on the audio thread (AR-6), command queue for data in (AR-4), immutable snapshots for structural edits (AR-5)
- Managed/native crossings go through the pure C ABI in
nota_engine.honly (AR-7); no JUCE outsidepluginhost/ - Smoke-test impact assessed: engine behaviour change → extend
tests/Nota.SmokeTest - User-visible change →
CHANGELOG.md[Unreleased]entry planned (and FEATURES.md / user docs via the nota-features / nota-docs skills when working with an agent that has them) - UI change → follows
DESIGN.md(Ember design language)