Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
description: "Tasks for loop record mode — Overdub / Replace"
Tasks: Loop record mode — Overdub / Replace
Input: Design documents from /specs/018-loop-record-replace/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md
Tests: Included. Constitution IV requires the smoke test to cover any engine behaviour change.
Organization: Grouped by user story. US1 (Replace) and US2 (Overdub unchanged) share the engine foundation. US3 is the switch, persistence and surfaces.
Format: [ID] [P?] [Story] Description
Phase 1: Setup
- T001 Create
tests/Nota.SmokeTest/LoopRecordModeTests.cswith the two-line SPDX header, aRun()that yields the groups below, and the helpers copied fromLoopSeamTests.cs(Beats,Looped,Notes). Register it as-- loop record mode --intests/Nota.SmokeTest/Program.cs, both in the full run (after loop seam) and in the--live-recordblock.
Phase 2: Foundational (engine + ABI)
⚠️ Blocks US1–US3
- T002 Add
int32_t passtoRecordedNoteinsrc/native/nota.engine/src/Engine.h. Update every construction site insrc/native/nota.engine/src/Engine_Render.cpp(drainLiveMidi,captureRoutedNotes,onLoopWrap's split lambda) to passrecordPass_. InonLoopWrapthe head gets the old pass and the continuation the new one. - T003 Add the mode and pass state to
src/native/nota.engine/src/Engine.h:std::atomic<bool> loopRecordReplace_{false}withsetLoopRecordReplace(bool)/loopRecordReplace(), audio-threadint32_t recordPass_ = 0; bool passReplace_ = false; bool passTriggered_ = false;,std::atomic<int32_t> replaceUpTo_{0}, and message-threadstruct TakeNote { int32_t pitch; double absStart; int32_t pass; }; std::vector<TakeNote> takeNotes_; int32_t appliedReplaceUpTo_ = 0;. - T004 Reset the pass state on the audio thread when a take starts. In
drainLiveMidi(src/native/nota.engine/src/Engine_Render.cpp), ontakeStartedsetrecordPass_ = 0,passTriggered_ = false,passReplace_ = loopRecordReplace_.load(relaxed),replaceUpTo_.store(0, release). InEngine::setRecording(true)(src/native/nota.engine/src/Engine_Recording.cpp) cleartakeNotes_and setappliedReplaceUpTo_ = 0beforerecording_goes true. - T005 In
Engine::onLoopWrap(src/native/nota.engine/src/Engine_Render.cpp), for an Arrangement take only (recording, norecordSlotPlayer_), after the split:++recordPass_,passTriggered_ = false,passReplace_ = loopRecordReplace_.load(relaxed). - T006 [P] Add the C ABI per
specs/018-loop-record-replace/contracts/c-abi.md. Declarenota_transport_set_loop_record_modeandnota_transport_loop_record_modeinsrc/native/nota.engine/include/nota/nota_engine.hnext to the count-in calls, and implement them insrc/native/nota.engine/src/nota_engine_core.cpp("mode outside {0, 1} → NOTA_ERR_INVALID_ARG"). - T007 [P] Add the managed mirror.
SetLoopRecordMode(bool replace)andbool LoopRecordReplace { get; }go insrc/managed/Nota.Application/Engine/IAudioEngine.cs. P/Invokes go insrc/managed/Nota.Infrastructure/Interop/NativeMethods.cs, and wrappers insrc/managed/Nota.Infrastructure/Interop/NotaEngine.cs. Implement it in any otherIAudioEngineimplementers or fakes (grepSetCountIn(to find them).
Checkpoint: Builds. Recording behaves exactly as before (no trigger yet).
Phase 3: User Story 1 — Re-record a loop until it's right (P1) 🎯 MVP
Goal: In Replace, the first fresh note of a new pass removes this take's earlier passes.
Independent test: quickstart.md rows "Replace, same phrase on 5 passes", "silent pass", "existing clip notes", "held across seam", "routed".
- T008 [US1] Trigger on the audio thread (
src/native/nota.engine/src/Engine_Render.cpp). IndrainLiveMidi, where a recorded live note-on setspendingActive_, and incaptureRoutedNoteson a routed note-on, when!recordSlotPlayer_andpassReplace_ && !passTriggered_ && recordPass_ > 0:replaceUpTo_.store(recordPass_, release); passTriggered_ = true;. The seam continuation inonLoopWrapmust not trigger. - T009 [US1] Apply on the message thread in
collectRecorded(src/native/nota.engine/src/Engine_Render.cpp). LoadreplaceUpTo_with acquire before drainingrecorded_. In the Arrangement branch, skip batch notes withpass < replaceUpToand push{pitch, absStart, pass}totakeNotes_for each appended note. Then, ifreplaceUpTo > appliedReplaceUpTo_, erase fromclip.notesevery note matching atakeNotes_entry withpass < replaceUpTo(same pitch,|clip.startBeat + n.startBeat − absStart| < 1e-6), drop those entries, and setappliedReplaceUpTo_. Also handle a batch that is empty but has a pending replace (don't early-return before applying), and publish viarepublishWithTrackRaw(same undo step). Session-slot branch: unchanged. - T010 [US1] Smoke tests in
tests/Nota.SmokeTest/LoopRecordModeTests.cs(mode set via the new ABI, 1-bar loop at 120 BPM):- (a) Replace, the same 4-note phrase on 5 passes with ±0.03-beat jitter → exactly 4 notes, all from the last pass.
- (b) Replace, play on pass 1, nothing on pass 2, stop → pass-1 notes kept.
- (c) Replace into an existing clip that holds a note at beat 2.0 → that note survives.
- (d) Replace, hold a key 3.5 → seam → 0.5, then a fresh note at 1.0 on the same pass → the head
3.5+0.5is gone, while0.0+0.5and the fresh note stay. A further fresh note on the next pass removes them. - (e) Replace with routed MIDI (
SetTrackMidiSource+TrackNoteOnon the source) → same result as (a) with 3 passes.
Checkpoint: US1 works headless.
Phase 4: User Story 2 — Keep overdubbing (P1)
Goal: Overdub is unchanged and is the default.
- T011 [US2] Smoke tests in
tests/Nota.SmokeTest/LoopRecordModeTests.cs:- (f) default mode on a fresh engine reads overdub (
LoopRecordReplace == false). - (g) Overdub, a different pitch on each of 3 passes → all 3 pitches present.
- (h) the ABI round-trip works, and an invalid mode (2) returns an error (call the
NativeMethodsentry directly, or check that the wrapper throws).
- (f) default mode on a fresh engine reads overdub (
Phase 5: User Story 3 — Switch quickly, even while recording (P2)
Goal: One click or ⌘⇧R toggles the mode. The mode is visible, persisted and reachable from MCP. A mid-take switch applies from the next pass.
- T012 [US3] Smoke test (i) in
tests/Nota.SmokeTest/LoopRecordModeTests.cs: start in Overdub, play on pass 1, switch to Replace during pass 2 after playing a note in it, play on pass 3. Expected: pass-1 and pass-2 notes are removed only at pass 3's first note, and the pass-2 note did not trigger a replace when played. - T013 [P] [US3] Add
public bool LoopRecordReplace { get; set; }(defaultfalse) tosrc/managed/Nota.Application/Settings.cs, next toCountInBars, with a doc comment. - T014 [US3] Add
[ObservableProperty] private bool _loopRecordReplace;tosrc/managed/Nota.Presentation/ViewModels/TransportViewModel.cs, withpartial void OnLoopRecordReplaceChanged(bool value) => _engine.SetLoopRecordMode(value);and aToggleLoopRecordModerelay command. Also add aLoopRecordModeText("Overdub"/"Replace") if the cell needs a bound label. - T015 [US3] Restore and persist in
src/managed/Nota.App/MainWindow.axaml.cs: setvm.Transport.LoopRecordReplace = vm.Settings.Current.LoopRecordReplacewhereCountInBarsis restored (~line 347), and write it back plus save on change (subscribe toPropertyChanged, the same way other transport preferences are saved; find howSettingsis saved). - T016 [US3] Add the transport console cell to
src/managed/Nota.App/MainWindow.axamlright after the Loop cell, perspecs/018-loop-record-replace/contracts/ui.md: aToggleButton Classes="cell"bound toTransport.LoopRecordReplace, labelled Overdub/Replace, with the tooltip from the contract. Follow DESIGN.md / the nota-design skill. Add a separator if the Loop group uses one. - T017 [US3] Add the command
C("transport.loopRecordMode", "Loop record: overdub / replace", "Transport", "⌘⇧R", "overdub replace take pass")tosrc/managed/Nota.Application/Palette/CommandCatalog.cs. Bind it insrc/managed/Nota.App/MainWindow.Commands.cs(B("transport.loopRecordMode", ...)togglingTransport.LoopRecordReplace). Check that ⌘⇧R is not handled elsewhere insrc/managed/Nota.App/MainWindow.Input.cs. - T018 [US3] Add the menu item
<NativeMenuItem Header="Loop Record: Replace" app:Commands.Id="transport.loopRecordMode"/>under Transport insrc/managed/Nota.App/MainWindow.axaml, next to Loop and Metronome, with a check state if other toggle items show one. - T019 [P] [US3] MCP in
src/managed/Nota.Mcp/Tools/TransportTools.cs: addbool LoopRecordReplacetoTransportState/get_transport, and add aset_loop_record_mode(bool replace)tool. Route it through the same state the UI uses (view-model or engine plus settings) so the toggle reflects it. Update any MCP tool listing or test that enumerates tools (grepset_metronomeintests/).
Checkpoint: The UI toggle, shortcut, menu, MCP and persistence all work.
Phase 6: Polish & cross-cutting
- T020 Add a
CHANGELOG.md[Unreleased] → Addedentry: "Loop recording: Overdub or Replace (nota-daw/nota#29)". - T021 Run the nota-shortcuts skill (Preferences → Shortcuts list gains ⌘⇧R), the nota-features skill (FEATURES.md), and the nota-docs skill (recording page, EN + RU).
- T022 Run
scripts/build.sh. It must pass, including the new-- loop record mode --group. - T023 Verify the UI headless or in the app per the "Nota UI verify recipe" memory: the transport cell renders in both states in Studio Dark and Light, and ⌘⇧R toggles it.
- T024 Re-check the Nota Compliance Checklist in
specs/018-loop-record-replace/spec.mdand run/speckit-converge. - T025 Commit on
fix/loop-seam-note-cutasEgor Khindikaynen <[email protected]>, with no Co-Authored-By, separately from the seam-fix commit.
Dependencies
- T001 → T010–T012 (test file).
- T002–T005 (engine state) → T008–T009 → T010.
- T006 → T007 → T010–T019 (tests and the app use the ABI).
- US1 (T008–T010) and US2 (T011) are independent once Phase 2 is done.
- US3 UI (T013–T018) depends only on T007. T012 depends on T008–T009.
- Polish depends on everything.
Parallel opportunities
- T006 ∥ T002–T005 (different files). T007 after T006.
- T013 ∥ T019 ∥ T017 (different files) once T007 is done.
Implementation strategy
MVP = Phase 2 + US1 (Replace works headless and is tested). Then US2 (guard rails), then US3 (surfaces), then polish. One commit at the end, per the user's workflow.
Implementation notes (2026-10-16)
- T011 (h): the managed wrapper takes a
bool, so a test cannot pass an out-of-range mode. The C ABI rejects modes outside {0, 1}, as the code shows. The smoke test covers the default and the set/get round-trip. - T016 / T018: the toggle label sizes to the longer word ("Overdub") so the transport bar doesn't shift between states. The menu item reads Loop record: overdub / replace, a plain command, because the design-token check requires sentence case. It is not a check item. The cell also joins the transport's narrow-width shed order (
MainWindow.TransportFit.cs), and is shed before Loop. - T019: MCP sets the engine directly, as
set_metronomedoes.TransportViewModel.Tickfollows the engine's mode, so the toggle and the saved preference update either way. - T023: verified headless (
/tmp/loopmodeharness). Clicking the toggle, ⌘⇧R, and the MCP/engine path all update the engine, the VM, the label and the saved preference. Plain ⌘R still records. The cell is 58 px in both states. Screenshots were taken in Studio Dark and Light, and the setting survived a restart. The Shortcuts pane lists ⌘⇧R.
Phase 7: Convergence
- T026 When
collectRecorded(src/native/nota.engine/src/Engine_Render.cpp) removes earlier-pass notes in Replace mode, release their voices: queue an audio-thread command (AR-4, allocation-free) carrying the record track id and the removed pitches. In the next block, before rendering, inject note-offs for those pitches into that track's MIDI (through its MIDI FX, like the seam offs), skipping any pitch the player is holding live on that track right now. Do not route it throughtrackNoteOff, which would end a note being recorded. Per SC-005 / FR-003 (contradicts). - T027 Add a smoke test to tests/Nota.SmokeTest/LoopRecordModeTests.cs: Replace, a long note on pass 0 (0.1 → 3.6), polled so it plays back on pass 1, then a fresh note on pass 1 while it sounds → after release, a pass with no notes in the take is silent (rms < 1e-4). Run the same scenario in Overdub as a control: it still sounds. Per SC-005 / Constitution IV (missing).