Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
description: "Task list for piano-roll note editing: overwrite, in-place paste, length and velocity keys"
Tasks: MIDI Note Editing — Overwrite, In-Place Paste, Length & Velocity Keys
Input: Design documents from specs/007-midi-note-editing/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/piano-roll-keys.md, quickstart.md
Tests: Included. The plan and quickstart §1 call for a pure-logic smoke-test section
(NoteEditingTests, --notes). Write each test task before its implementation and see it
fail first (a compile failure on the missing type counts).
Organization: By user story (spec.md): US1 notes overwrite (P1), US2 paste on the original (P1), US3 length keys (P2), US4 velocity keys (P2).
Format: [ID] [P?] [Story] Description
- [P]: Can run in parallel (different files, no dependencies on incomplete tasks)
- [Story]: US1–US4
Path Conventions
- Rule (pure):
src/managed/Nota.Application/Editing/ - App and views:
src/managed/Nota.App/ - Tests:
tests/Nota.SmokeTest/ - Every new
.csfile starts with the two-line SPDX header from CONTRIBUTING.md and a short comment header explaining why the file exists (matchSnapGrid.cs). - Line numbers are as of
developat 648d7ab and drift as you edit, so search by member name.
Phase 1: Setup
- T001 Create
tests/Nota.SmokeTest/NoteEditingTests.cswith the SPDX header, a comment header ("Piano-roll note editing (specs/007-midi-note-editing): the overwrite rule, length and velocity steps. Also runnable alone:dotnet run --project tests/Nota.SmokeTest -- --notes."), andinternal static class NoteEditingTests { public static IEnumerable<(bool Ok, string Label)> Run() { yield break; } }, followingSnapGridTests.cs. - T002 Wire it into
tests/Nota.SmokeTest/Program.cs:- add a
--notesearly-exit block printing-- note editing --andNOTES PASSED/NOTES FAILED (n), next to the--gridblock (around line 227); - in the full run, add
Console.WriteLine("-- note editing --"); foreach (var (ok, label) in NoteEditingTests.Run()) Check(ok, label);right after the snap-grid section (around line 14548).
- add a
Phase 2: Foundational (blocks every story)
- T003 Create
src/managed/Nota.Application/Editing/NoteOverwrite.cs(namespaceNota.Application.Editing, SPDX header, comment header citing the spec), with type stubs only:enum NoteFateKind { Kept, Cut, Removed },readonly record struct NoteFate(NoteFateKind Kind, double CutLength), and astatic class NoteOverwritewhose methods throwNotImplementedException. US1, US3 and US4 fill in the bodies.
Checkpoint: dotnet build src/managed/Nota.App/Nota.App.csproj and the test project build.
Phase 3: User Story 1 — Notes overwrite instead of stacking (P1) 🎯 MVP
Goal: Placed notes overwrite same-pitch notes once the selection is let go; until then the notes underneath are only marked.
Independent Test: quickstart §2 rows 1 and 2, plus --notes.
Tests (write first)
- T004 [P] [US1] In
tests/Nota.SmokeTest/NoteEditingTests.cs, add overwrite cases, each yielding one labelled check:- the spec's Story 1 scenarios 1–3 through
NoteOverwrite.Settle(A cut to 0–1; A removed; A removed by a lengthened B); - different pitches untouched (scenario 4);
- two placed notes overlapping each other are both kept unchanged;
- an unplaced note fully inside a placed one is removed;
- an unplaced note run into by two placed notes is cut at the earliest placed start;
placedOutindices point at the same notes after removals;- a copy exactly on its original (same start) removes the original;
Fateagrees withSettlefor every unplaced note in these fixtures;- ε handling: an unplaced note ending exactly at a placed start (within 1e-9) is Kept.
- the spec's Story 1 scenarios 1–3 through
Implementation
- T005 [US1] In
src/managed/Nota.Application/Editing/NoteOverwrite.cs, implement the data-model.md §1 rule verbatim:public static NoteFate Fate(in NotaNote m, IReadOnlyList<NotaNote> notes, IReadOnlyCollection<int> placed)— "c.Start − ε ≤ m.Start < c.End − ε→ Removed;m.Start < c.Startandm.End > c.Start + ε→ Cut toc.Start − m.Start(shortest over all such c); otherwise Kept"; "Removal wins over a cut"; same pitch only; ε = 1e-9. Allocation-free (it is called per frame from Render).public static void Settle(IReadOnlyList<NotaNote> notes, IReadOnlyCollection<int> placed, List<NotaNote> output, List<int> placedOut)— placed notes unchanged, survivors in original order,placedOutthe new indices of the placed notes. Rundotnet run --project tests/Nota.SmokeTest -- --notes; the T004 checks must pass.
- T006 [US1] In
src/managed/Nota.App/PianoRollView.csDuplicateSelection(around line 461), replace the inline overwrite loop withNoteOverwrite.Settleover_notes + copies, with the copies asplaced, and keep the behaviour identical (FR-009). Select the copies viaplacedOut. - T007 [US1] In
src/managed/Nota.App/PianoRollView.cs, add the pending placement:- a
private bool _placementPendingfield; public bool SettlePlacement(): return false unless pending; clear the flag; if the selection is empty, return false; otherwiseNoteOverwrite.Settle(_notes, _selection, …). If nothing changed (same count and no cut), return false without committing. Otherwise replace_notes, rebuild_selectionfromplacedOut,Invalidate(); CommitNotes(); Changed?.Invoke();(one undo step, FR-002) and return true;- a
private void MarkPlaced() => _placementPending = true;helper.
- a
- T008 [US1] In
src/managed/Nota.App/PianoRollView.cs, set pending after placements:NoteGrid.OnPointerReleasedwhenwas != Mode.Marquee && _dragMoved(move, resize, resize-left);MoveSelectionafter a successful move;- the double-click draw branch in
NoteGrid.OnPointerPressed(the new note is selected).
- T009 [US1] In
src/managed/Nota.App/PianoRollView.cs, settle before every selection change and whole-clip edit:- In
NoteGrid.OnPointerPressed, when the press will change the selection (double-click; Shift-click toggle; hit not in the selection; empty-space marquee), call_o.SettlePlacement()first and, if it returned true, re-runHitTest(p, out edge), because indices may have shifted. A press on an already-selected note without Shift must not settle. - Also settle on Esc and ⌘A in
NoteGrid.OnKeyDown, and at the start ofDuplicateSelection,Quantize,TransposeByandRemoveOutOfScaleNotes. (Implemented:ShowPreview/ApplyPreviewclear the flag instead of settling — the tool computed its result from the unsettled notes and its captured indices would go stale; focus loss on clicking the tools rail settles first anyway.)
- In
- T010 [US1] In
src/managed/Nota.App/PianoRollView.cs, clear_placementPendingwithout settling inSetNotes(a reload or undo means the engine wins) and inDeleteSelection. - T011 [US1] In
src/managed/Nota.App/PianoRollView.csNoteGrid, overrideOnLostFocusto call_o.SettlePlacement()(research R5: this also covers switching clips, since the old roll loses focus while itsCommitstill targets its own clip). - T012 [US1] In
src/managed/Nota.App/MainWindow.Files.cs, call_editorRoll?.SettlePlacement();:- before
_projects.Save((around line 306), and before the save-as picker so a cancelled dialog has still settled; - at the top of
DoExportAsync(around line 51). Autosave (MainWindow.Recovery.cs) is left alone (R5). Check that project-version saves (MainWindow.History.cs) go through the same save method; if not, add the call there too.
- before
- T013 [US1] In
src/managed/Nota.App/PianoRollView.csNoteGrid.Render(the note loop around line 1034), when_o._placementPendingand the note is not selected and not a ghost, computeNoteOverwrite.Fate(n, notes, _o._selection):Removed: draw the whole note at ~25% of its normal alpha with a 1 px dashed outline in the track colour;Cut: draw[start, start+cutLen)normally and the rest faded and dashed. Use static pens and brushes cached per track colour (no per-frame allocation beyond what the loop already does), keep it distinguishable from the brass tool-preview ghost, and check againstDESIGN.mdwith the nota-design skill (research R4).
Checkpoint: quickstart rows 1–2 behave; Duplicate is unchanged; --notes passes.
Phase 4: User Story 2 — Copy/paste lands on the original (P1)
Goal: ⌘V always lands on the copied notes' own beats, with the copies selected and pending.
Independent Test: quickstart §2 rows 3–5.
- T014 [US2] In
src/managed/Nota.App/PianoRollView.csPasteClipboard(around line 685):- call
SettlePlacement()first; - replace
double anchor = _playheadBeat >= 0 ? SnapBeat(_playheadBeat) : s_clipAnchor;withdouble anchor = s_clipAnchor;; - after selecting the pasted notes, call
MarkPlaced(), so the paste itself overwrites nothing (FR-003a); - update the doc comment ("on top of the copied notes' original position"). Skip and trim at the clip end as today (data-model §5).
- call
- T015 [US2] In
src/managed/Nota.App/MainWindow.Menu.cs(the paste handler around line 162), confirm the Edit-menu paste reaches the samePasteClipboard. No change is expected; record the result in the task. (Confirmed:OnMenuPaste→ActiveRoll().PasteClipboard().)
Checkpoint: US1 and US2 together give the requested "paste on top, then move" workflow.
Phase 5: User Story 3 — Stretch and shrink from the keyboard (P2)
Goal: ⇧←/⇧→ shorten or lengthen every selected note by one grid step.
Independent Test: quickstart §2 row 6, plus --notes.
Tests (write first)
- T016 [P] [US3] In
tests/Nota.SmokeTest/NoteEditingTests.cs, addNoteOverwrite.ResizeBycases:- +step grows every note with starts unchanged;
- −step on a note of length
minLenleaves it atminLen; - a note ending at the clip end does not grow while the others do;
- it returns false when nothing changed.
Implementation
- T017 [US3] In
src/managed/Nota.Application/Editing/NoteOverwrite.cs, implementpublic static bool ResizeBy(List<NotaNote> notes, IEnumerable<int> indices, double delta, double minLen, double clipLength)per data-model §3: "len' = clamp(len ± step, MinNoteLen, clipLength − start), withstartunchanged". - T018 [US3] In
src/managed/Nota.App/PianoRollView.cs, addpublic bool ResizeSelection(int dir):- step =
SnapGridState.SnapOn ? SnapStep : MinNoteLen(R7); - call
ResizeBy(_notes, _selection, dir * step, MinNoteLen, _lengthBeats); - on change,
Invalidate(); CommitNotes(); Changed?.Invoke(); MarkPlaced();.
- step =
- T019 [US3] In
src/managed/Nota.App/PianoRollView.csNoteGrid.OnKeyDown(around line 1417), inside the!meta && selectionblock, handleKey.LeftandKey.Rightwithshift(and no Alt) as_o.ResizeSelection(-1 / +1)before the plain nudge cases. Plain ←/→ stay as they are.
Phase 6: User Story 4 — Velocity from the keyboard (P2)
Goal: ⌥↑/⌥↓ change velocity by ±10, and ⌥⇧↑/⌥⇧↓ by ±1.
Independent Test: quickstart §2 rows 7–8, plus --notes.
Tests (write first)
- T020 [P] [US4] In
tests/Nota.SmokeTest/NoteEditingTests.cs, addNoteOverwrite.VelocityBycases: 40/127 + 10 → 50/127; 125/127 + 10 → 127/127; 3/127 − 10 → 1/127; 0.8f + 1 → (round(0.8·127)+1)/127; the result is always on an integer MIDI step.
Implementation
- T021 [US4] In
src/managed/Nota.Application/Editing/NoteOverwrite.cs, implementpublic static float VelocityBy(float v, int steps127)per data-model §4: "v' = clamp(round(v·127) + k, 1, 127) / 127". - T022 [US4] In
src/managed/Nota.App/PianoRollView.cs, addpublic bool NudgeVelocity(int steps127). It appliesVelocityByto every selected note; if any changed,Invalidate(); CommitNotes(); Changed?.Invoke();. It does not touch_placementPending. The velocity lane and theSelectionInfotext refresh throughChanged/Invalidate. - T023 [US4] In
src/managed/Nota.App/PianoRollView.csNoteGrid.OnKeyDown, readbool alt = (e.KeyModifiers & KeyModifiers.Alt) != 0;. In the selection block, check Alt before Shift:Key.Up/Key.Downwith Alt →_o.NudgeVelocity(shift ? ±1 : ±10). Leave Alt+←/→ unhandled. Without a selection, the keys fall through (contract).
Phase 7: Polish & Cross-Cutting
- T024 [P] In
src/managed/Nota.App/PreferencesWindow.cs(the "PIANO ROLL" group around line 1074), add rows per contracts/piano-roll-keys.md:("⇧← ⇧→", "Shorten / lengthen the notes by the grid");("⌥↑ ⌥↓", "Velocity +10 / −10 · ⌥⇧ by 1");- change ⌘C ⌘X ⌘V to "Copy / cut / paste notes · paste lands on the originals";
- add
("Esc", "Deselect · applies the overwrite of moved notes"). Run the nota-shortcuts skill to confirm the list matches the handlers.
- T025 [P] Add
CHANGELOG.md[Unreleased]entries:- Changed: "Notes moved, stretched, drawn or pasted onto notes of the same pitch now replace them instead of stacking — applied when you deselect; until then the notes underneath are marked." and "⌘V in the piano roll always pastes on top of the copied notes."
- Added: "⇧←/⇧→ shorten or lengthen the selected notes by the grid; ⌥↑/⌥↓ change their velocity by 10 (⌥⇧ by 1)."
- T026 [P] Update
FEATURES.mdwith the nota-features skill. - T027 [P] Update the piano-roll page in
../nota-docs(EN + RU) and regenerate the shortcuts page with the nota-docs skill. - T028 Run
scripts/build.sh(builds native + managed and runs the full smoke test, including-- note editing --); it must exit green. - T029 Walk quickstart §2 rows 1–9 in the real app (the memory's UI verify recipe,
NOTA_DATA_DIRisolation) and take screenshots of row 2 (the mark) and row 9 (Shortcuts). - T030 Recheck the spec's Nota Compliance Checklist: SPDX headers on
NoteOverwrite.csandNoteEditingTests.cs, no new dependency, CHANGELOG present.
Dependencies & Execution Order
- Setup (T001–T002) → Foundational (T003) → stories.
- US1 (T004–T013) comes first: US2 and US3 call
MarkPlaced/SettlePlacement. - US2 (T014–T015) depends on T007.
- US3 (T016–T019) depends on T003 and T007 (
MarkPlaced). Its rule work (T016–T017) can run alongside US1. - US4 (T020–T023) depends only on T003, so it is independent of US1–US3 at the rule level. T023 touches the same
OnKeyDownas T019, so do them one after the other. - Polish comes after the stories it documents.
Inside PianoRollView.cs everything is sequential (same file).
Parallel Examples
# After T003:
T004 (overwrite tests) T016 (resize tests) T020 (velocity tests) — same test file: write in one sitting, or one after another
T017 (ResizeBy) T021 (VelocityBy) — same file as T005: one after another
# Polish:
T024 T025 T026 T027 — different files
Implementation Strategy
- MVP = US1 + US2 (both P1): overwrite with deferred settle, and paste on the original. This is the user's core workflow ("paste on top, move with arrows").
- Then US3 (length keys), then US4 (velocity keys). Each is a small key handler over a tested pure step.
- Polish: shortcuts list, CHANGELOG, FEATURES, docs,
scripts/build.sh, app walkthrough.
Phase 8: Convergence
- T031 Settle the pending placement before the velocity lane and the MPE expression lanes change the selection. Without this, a stem click swaps the selection while
_placementPendingstays true, and the next settle treats the clicked note as placed. Insrc/managed/Nota.App/PianoRollView.cs,VelocityLane.OnPointerPressed: call_o.SettlePlacement()before_selectionchanges (and re-runNearest(p)if it returned true). Do the same insrc/managed/Nota.App/PianoRollView.Expression.csExpressionLane.TargetsAtbefore it clears or adds to_selection. Neither lane is focusable, so the grid'sLostFocusdoes not fire. Add a/tmp/noteharnesscase: paste, press →, then click another note's stem — that note must not overwrite anything — per FR-003 (contradicts) - T032 Settle instead of silently dropping a pending placement when the roll is reloaded or replaced for any reason other than undo/redo. In
src/managed/Nota.App/MainWindow.Detail.cs,ReloadEditorNotes(reached fromTracksChanged,RecordingTickand pattern-view edits) and both_editorRoll = roll;sites (lines ~437 and ~616, where a clip editor that never had focus can be replaced): call_editorRoll?.SettlePlacement()first. KeepRefreshAfterUndoRedo(MainWindow.Menu.cs) discarding, because there the engine state wins. That way a later save never stores the stacked notes, per SC-001 / FR-003 (partial) - T033 Reconcile the clip-tool preview with plan §2:
src/managed/Nota.App/MidiToolsView.cs(line ~160) captures_roll.SourceNotes/SelectionIndiceswithout settling, andShowPreview/ApplyPreviewdrop the pending flag (the tasks.md T009 note). Call_roll.SettlePlacement()right before that capture, so a tool never builds on stacked notes even when the grid kept focus, per plan: settle before whole-clip edits (contradicts) (Implemented in part: the two_editorRoll = roll;sites now settle the outgoing roll.ReloadEditorNotesis deliberately left discarding. Every caller (pattern-view edit, recording tick,TracksChanged) means the engine changed underneath, so settling there would commit the roll's stale note list over that external change. That is the plan's R5 / §2 rule "a reload means the engine state wins". SC-001 holds for edits made in the roll; a placement interrupted by an external reload keeps the engine's notes as they are.) (T033 implemented atMidiToolsView.Preview(), not atResync():Resyncruns after every roll edit and would settle immediately.)