Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
Implementation Plan: Multi-select devices and group them into a rack
Branch: feat/device-multiselect-group | Date: 2026-10-27 | Spec: spec.md
Input: Feature specification from specs/044-device-multiselect-group/spec.md
Summary
The track's device chain gets a multi-selection (Shift-click range, ⌘/Ctrl-click toggle) across MIDI effects, the instrument and audio effects. Copy / Cut / Paste / Delete / Duplicate / drag / Move to track ▸ act on the whole selection as one undo step. ⌘G groups a contiguous selection into the matching rack (Audio Effect, Instrument or MIDI Effect Rack), and ⌘⇧G ungroups any one-chain rack; both are one publish and one undo step, and the track sounds the same.
Per the clarification, automation lanes, CV links, sidechain keys and Arp CC routes travel
into the rack and back. That needs the engine's one real addition: a nested parameter
address (ParamPath: host device → chain uid → slot) used by automation, CV, the Arp CC
route (moved into the undo snapshot) and the sidechain feed, resolved on the audio thread by
reading the rack's published snapshot. On top of that: general groupDevices /
ungroupRack operations replacing the single wrap / unwrap (#257), a multi-entry device
clipboard, project-format fields for nested lanes, and the selection model, menus and keys in
DeviceChainView. See research.md R1–R11.
Nota: Read Before Planning
- Engine work →
ARCHITECTURE.md: AR-5 (Group / Ungroup / Paste each publish one graph), AR-6 (the nested resolver only reads published snapshots — no allocation or lock on the audio thread), AR-7 (new calls only innota_engine.h). - UI work →
DESIGN.mdand thenota-designskill (multi-selection borders, the menu header with a count, disabled items). - Anything →
CONTRIBUTING.md.
Technical Context
Language/Version: C++20 (engine), C# / .NET 10 + Avalonia (app, presentation, MCP)
Primary Dependencies: None new
Storage: Project file — automation-lane, CV-link and Arp-CC-route DTOs gain optional
Chain / Slot fields (format version bump; old projects load unchanged, R7). The clipboard is
not persisted.
Audio-Thread Impact: applyAutomation, applyMidiCcRouting, the CV apply pass and the
sidechain feed resolve nested targets by scanning the rack's published RackState chains
(no allocation, no lock, AR-6). Group / Ungroup / Paste build off-graph and publish once
(AR-5); moved instances are not re-prepared, so tails and held notes continue.
Testing: tests/Nota.SmokeTest — new DeviceGroupTests.cs (engine through the C ABI:
group / ungroup per rack type, render equality before / after, nested lanes / CV / CC /
sidechain, undo, save-reload, multi-clipboard) and DeviceSelectionTests.cs (the selection
model, headless). UI checked in the running app per quickstart.md.
Target Platform: macOS, Windows, Linux desktop
Project Type: Desktop app (native engine + managed UI)
Performance Goals: Group / Ungroup during playback: no dropout (SC-006), the edit under one UI frame; render before vs after Group within 0.1 dB (SC-003); nested resolve adds no measurable block time (checked with the existing engine perf gate).
Constraints: One undo step per user action (FR-020); racks nest one level (specs/041); Ungroup only for one-chain racks.
Scale/Scope: ~6 engine files (+1 helper), ~6 C ABI calls, ~10 managed files, 1 MCP tool pair, 2 smoke files
Constitution Check
GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.
| Principle | Status | Notes |
|---|---|---|
| I. Real-time audio safety | Pass | Nested resolve reads the published rack snapshot only (R2); structural edits publish once (R3) |
| II. Boundary discipline | Pass | New calls in nota_engine.h (contracts/c-abi.md); no JUCE outside pluginhost/ |
| III. Licensing hygiene | Pass | New files carry the SPDX header; no dependencies |
| IV. Verification gate | Pass | DeviceGroupTests covers every new C ABI call; scripts/build.sh before the PR |
| V. One logical change | Pass, noted | One issue (#328); the nested address is its prerequisite and lands in the same PR, first commit(s) |
| VI. Docs in sync | Planned | CHANGELOG [Unreleased], FEATURES.md (nota-features), user docs (nota-docs), Shortcuts pane (nota-shortcuts) |
| VII. Spec-first | Pass | spec.md with 3 clarifications, this plan, tasks.md next |
| VIII. Rules not weakened | Pass | — |
Post-design re-check (after Phase 1): unchanged — the contracts add audio-thread reads of already-published data only, and cross the boundary only through the C ABI.
Project Structure
Documentation (this feature)
specs/044-device-multiselect-group/
├── spec.md
├── plan.md # this file
├── research.md # R1–R11
├── data-model.md # ParamPath, selection, clipboard, group shape
├── quickstart.md # end-to-end checks in the app + smoke
├── contracts/
│ ├── c-abi.md # new / changed nota_engine.h calls
│ ├── ui.md # gestures, menus, keys, status messages
│ └── mcp.md # group_devices, ungroup_rack
├── checklists/requirements.md
└── tasks.md # /speckit-tasks
Source Code (repository root)
src/native/nota.engine/
├── include/nota/nota_engine.h # + group/ungroup, multi copy/paste, nested lane/CV info
└── src/
├── abi/
│ ├── nota_engine_device.cpp # group / ungroup / copy_devices / paste_devices wrappers
│ └── nota_engine_automation.cpp # nested lane info + add (for load)
├── devices/
│ ├── MidiDevice.h # CC destination leaves the device (R4)
│ └── racks/RackCore.h/.cpp # setChainInstrumentInstance; child walk helper for the feed
└── engine/
├── ParamPath.h # new: the nested address + resolver declaration (R1)
├── Automation.h, Modulation.h, Track.h # lanes, CV links, CC routes carry chain/slot
├── Engine.h
├── Engine_Rack.cpp # groupDevices / ungroupRack (R3), remapPathsAfterRackEdit (R6)
├── Engine_Automation.cpp # applyAutomation via resolver; remap helpers take paths
├── Engine_Modulation.cpp # CV apply / remap via paths
├── Engine_Render.cpp # applyMidiCcRouting + sidechain feed walk rack chains (R4, R5)
└── Engine_Devices.cpp # multi-entry clipboard (R8), route claims walk racks
src/managed/
├── Nota.Application/Engine/IAudioEngine.cs, EngineContracts.cs # GroupDevices, UngroupRack, CopyDevices, PasteDevices, lane Chain/Slot
├── Nota.Infrastructure/
│ ├── Interop/NativeMethods.*.cs, NotaEngine.*.cs # P/Invoke
│ └── Persistence/ProjectService.cs # Chain / Slot on lane, CV, CC-route DTOs (R7)
├── Nota.App/
│ ├── DeviceSelection.cs # new: the selection model (R9)
│ ├── DeviceChainView.Clipboard.cs # selection gestures, batch ops, ⌘G / ⌘⇧G, menus
│ ├── DeviceChainView.Shell.cs # CardExtra.Wrapped → list (R10); selection border per card
│ ├── DeviceChainView.Move.cs # Move to track ▸ for a selection; multi drag-reorder
│ ├── DeviceChainView.Instruments.cs, DeviceChainView.Midi.cs # click modifiers on those cards
│ ├── ArrangementView.Automation.cs # nested lane titles ("Rack › Reverb · Mix")
│ └── PreferencesWindow (Shortcuts list) # Shift/⌘-click, ⌘G/⌘⇧G in Devices
└── Nota.Mcp/Tools/DeviceTools.cs # group_devices, ungroup_rack
tests/Nota.SmokeTest/
├── DeviceGroupTests.cs # new
├── DeviceSelectionTests.cs # new
├── Fixtures/ # an old-format project with an Arp CC lane (R4 migration)
└── Program.cs # run them; --device-group
Structure Decision: The existing engine / managed split. The nested address lives in one
new engine header used by the automation, modulation and render files; the UI work stays in
the DeviceChainView partials with the rules factored into DeviceSelection.
Phases (for /speckit-tasks)
- Foundation: nested address —
ParamPath+ resolver; lanes, CV links, Arp CC route (moved into the snapshot, with load migration) and the sidechain feed / route claims go through it;remapPathsAfterRackEditon rack chain edits; nested lane info in the ABI; persistence fields; smoke tests for each consumer. Behaviour today is unchanged (no nested paths exist until Group). - Engine Group / Ungroup —
groupDevices/ungroupRackfor the three rack types,setChainInstrumentInstance, path rewriting, old wrap / unwrap as wrappers; smoke: render equality, undo, save-reload. - US1 (P1) — ⌘G / ⌘⇧G and menu items on audio-effect selections (single and range).
- US2 (P1) —
DeviceSelection, gestures, borders, multi-entry clipboard (engine + UI), batch Delete / Cut / Duplicate / drag / Move to track ▸, confirmation with the instrument. - US3 (P2) — Instrument Rack group / ungroup from the UI.
- US4 (P3) — MIDI Effect Rack group / ungroup from the UI.
- MCP, nested lane titles, Shortcuts, CHANGELOG, FEATURES, docs; build + smoke + perf gate.
Complexity Tracking
No constitution violations. The nested address (phase 1) is the large part and exists only because of the FR-016 clarification; it is kept to one rack level and one shared resolver.