Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
C# audioaudio-unitavaloniacpp20cross-platformdawdigital-audio-workstationdspjucelinux-audiomcp-servermidimusicmusic-productionpiano-rollplugin-hostsequencersynthesizervstvst3
(feat) Record MIDI controllers with the notes: sustain pedal, wheels, any CC (#69) (#101)
Egor Khindikaynen11771f8ab93b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4019cbf4..e83aa32d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -30,6 +30,17 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.stays put. **Fit to notes** (⇧F, the "Fit" button in the clip editor header, or thecommand palette) zooms and scrolls so every note of the clip is in view. Each clipremembers its own zoom.+- **Record the sustain pedal, the wheels and any CC** (nota-daw/nota#69): recording MIDI now+ keeps the sustain pedal, the pitch wheel, the mod wheel, channel pressure and every other+ controller (expression, breath, CC74…) with the notes, and the clip plays them back to the+ instrument. Starting playback in the middle of a clip first sets each controller to where+ the clip has it (the pedal is already down), and when a clip ends or you stop, its pedal is+ released and the wheel centred, so no note hangs. A pedal already down when you press Record+ is in the take from its start. In loop recording, a pass replaces a controller only where+ you moved it: re-record just the pedal on the next pass and the notes stay. Controllers+ travel with the clip when you move, copy, split, trim or consolidate it, and are saved with+ the project. Polyphonic aftertouch from an ordinary keyboard is kept as each note's+ pressure. MCP: `get_clip_controllers`, `set_clip_controller`.### Fixed- **Notes no longer cut off at the loop seam** (nota-daw/nota#29): when the loop jumps@@ -66,6 +77,11 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.take, for keyboard and MIDI input and for MIDI routed in from another track.### Changed+- **Hosted plug-ins get every MIDI controller** (nota-daw/nota#69): the mod wheel and any+ other CC from your keyboard now reach a plug-in instrument (before, only the wheel, pressure,+ CC74 and the sustain pedal did), and the sustain pedal arrives with its real value, so a+ piano plug-in can half-pedal. Built-in synths with a Mod Wheel control (Bass, Monolith,+ Volt, Aurora, Operator, Pentad, Consort) follow the keyboard's mod wheel.- **Notes played on the count-in are recorded:** a pickup played during the count-in, or akey already held when recording starts, now lands in the take where it actually started.The take's clip begins earlier to include it. If the take starts at 1.1, the clip stilldiff --git a/FEATURES.md b/FEATURES.mdindex 7fadba4d..3ebc08c0 100644--- a/FEATURES.md+++ b/FEATURES.md@@ -286,6 +286,18 @@ track count and closes with Escape.Cmd/Ctrl+Shift+R or the Transport menu; applies from the next pass; remembered betweensessions. A note held across the loop seam is recorded as two notes, up to the loop endand on from the loop start.+- **MIDI controllers in clips** — recording keeps the sustain pedal, pitch wheel, mod wheel,+ channel pressure and any other CC with the notes (a pedal already down at Record is in the+ take from its start), and the clip plays them back to the instrument. Starting mid-clip sets+ each controller to the clip's value there; at a clip's end or on stop its pedals are+ released and the wheel centred. In loop recording a pass replaces a controller only over the+ range it moved it, so a pedal-only pass re-records the pedal and keeps the notes.+ Controllers move, copy, split, trim and consolidate with the clip and are saved with the+ project. Polyphonic aftertouch from an ordinary keyboard is kept as each note's pressure.+ Live and from clips, hosted plug-ins get every controller (the pedal with its real value, for+ half-pedalling); built-ins act on those they know — the pedal (Keys, Mosaic), the wheel,+ pressure, CC74, and the mod wheel on synths with a *Mod Wheel* control (Bass, Monolith, Volt,+ Aurora, Operator, Pentad, Consort). MCP `get_clip_controllers` / `set_clip_controller`.- **MPE (per-note expression)** — an MPE controller's notes each carry their own pitchbend, pressure and slide (CC74): channels 2–16 are per-note (lower zone, ±48 semitones bydefault; the controller's MPE Configuration and bend-range messages are honoured), channel 1@@ -295,12 +307,10 @@ track count and closes with Escape.Pentad: poly aftertouch through *Aftertouch Cutoff*, Physical: bows the struck body so a heldnote sustains); slide sweeps the filter (Aurora: the wavetable position, Operator: the FMindex, Physical: how long the body rings, Keys: drives the tine into the pickup / shifts its- symmetry). Instrument Racks pass it to their chains; hosted plug-ins get the wheel, channel- pressure, polyphonic aftertouch and the sustain pedal (CC64), which also holds Nota Keys'- notes. **Recording** keeps each note's bend, pressure and slide with the note: it plays back+ symmetry). Instrument Racks pass it to their chains; hosted plug-ins get polyphonic+ aftertouch (and every instrument-wide controller, see above). **Recording** keeps each note's bend, pressure and slide with the note: it plays backfrom the clip, moves, copies and quantizes with the note, is saved with the project, and the- piano roll draws it over the note (bend as the pitch it played, pressure as a shade). The- pitch wheel, channel pressure and sustain pedal aren't recorded.+ piano roll draws it over the note (bend as the pitch it played, pressure as a shade).- **MPE lanes in the piano roll** — the lane under the notes switches between **VEL**,**BEND**, **PRES** and **SLIDE**. In an MPE lane every note's curve sits over its ownspan; drag across a selected note to draw its curve (⌥ for a straight line), drag a point@@ -1082,7 +1092,7 @@ Coverage:- **Audio effects**: add, remove, reorder, bypass, parameters; load an audio file into adevice (a Nota Chamber impulse response) and read its resource text (IR names).- **MIDI clips and notes**: piano roll — add a clip, read/write/append/clear notes, move- and split.+ and split; read and write a clip's controller curves (sustain, wheels, any CC).- **Automation**: create a lane, read and write points.- **MIDI effects** and engine status.- **Session**: the clip launcher (grid snapshot with clip and scene properties, create, copy,diff --git a/specs/020-midi-cc-record-automate/checklists/requirements.md b/specs/020-midi-cc-record-automate/checklists/requirements.mdnew file mode 100644index 00000000..b59ceb12--- /dev/null+++ b/specs/020-midi-cc-record-automate/checklists/requirements.md@@ -0,0 +1,34 @@+# Specification Quality Checklist: Record and automate MIDI CC++**Purpose**: Validate specification completeness and quality before proceeding to planning+**Created**: 2026-10-16+**Feature**: [spec.md](../spec.md)++## Content Quality++- [x] No implementation details (languages, frameworks, APIs) — outside the template's Nota Context section, which is meant to carry them+- [x] Focused on user value and business needs+- [x] Written for non-technical stakeholders+- [x] All mandatory sections completed++## Requirement Completeness++- [x] No [NEEDS CLARIFICATION] markers remain (resolved 2026-10-16, see spec § Clarifications)+- [x] Requirements are testable and unambiguous+- [x] Success criteria are measurable+- [x] Success criteria are technology-agnostic (no implementation details)+- [x] All acceptance scenarios are defined+- [x] Edge cases are identified+- [x] Scope is clearly bounded+- [x] Dependencies and assumptions identified++## Feature Readiness++- [x] All functional requirements have clear acceptance criteria+- [x] User scenarios cover primary flows+- [x] Feature meets measurable outcomes defined in Success Criteria+- [x] No implementation details leak into specification++## Notes++- Items marked incomplete require spec updates before `/speckit-clarify` or `/speckit-plan`diff --git a/specs/020-midi-cc-record-automate/contracts/c-abi.md b/specs/020-midi-cc-record-automate/contracts/c-abi.mdnew file mode 100644index 00000000..caa56fa9--- /dev/null+++ b/specs/020-midi-cc-record-automate/contracts/c-abi.md@@ -0,0 +1,73 @@+# Contract: C ABI additions (`nota_engine.h`)++The functions below are pure C, use no C++ types, and are message-thread only unless+noted. Points use the existing `NotaAutomationPoint {beat, value, curve}`. Beats are+clip-local, or loop-local for slots, and values are normalised per [data-model.md](../data-model.md).++```c+/* ---- MIDI controllers (specs/020) ----------------------------------------+ * ctl: 0..127 = CC number, NOTA_CTL_PITCH_WHEEL, NOTA_CTL_CHANNEL_PRESSURE.+ * Values: CC 0..1 (data/127; CC64-69 on at >= 0.5), wheel -1..+1, pressure 0..1. */+#define NOTA_CTL_PITCH_WHEEL 128+#define NOTA_CTL_CHANNEL_PRESSURE 129+#define NOTA_CTL_COUNT 130++/* Arrangement MIDI clip. list fills the ctls that hold data (sorted) and returns the total+ * count (out may be NULL). get(out=NULL) returns the point count. set replaces the curve+ * (count 0 removes it); points sorted or not, at most one per beat; reserved CCs+ * (6, 38, 96-101, 120-127) are refused. One undo step; plays on the next block. */+NOTA_API int32_t nota_midi_clip_ctl_list(const NotaEngine* engine, int32_t track_id, int32_t clip_index, int32_t* out_ctls, int32_t cap);+NOTA_API int32_t nota_midi_clip_ctl_get (const NotaEngine* engine, int32_t track_id, int32_t clip_index, int32_t ctl, NotaAutomationPoint* out, int32_t cap);+NOTA_API NotaResult nota_midi_clip_ctl_set (NotaEngine* engine, int32_t track_id, int32_t clip_index, int32_t ctl, const NotaAutomationPoint* pts, int32_t count);++/* Session slot clip: same semantics, beats in [0, slot length). */+NOTA_API int32_t nota_session_ctl_list(const NotaEngine* engine, int32_t track_id, int32_t scene, int32_t* out_ctls, int32_t cap);+NOTA_API int32_t nota_session_ctl_get (const NotaEngine* engine, int32_t track_id, int32_t scene, int32_t ctl, NotaAutomationPoint* out, int32_t cap);+NOTA_API NotaResult nota_session_ctl_set (NotaEngine* engine, int32_t track_id, int32_t scene, int32_t ctl, const NotaAutomationPoint* pts, int32_t count);++/* Live controller input (any thread, lock-free producer like note_on): reaches armed /+ * audition tracks (engine_) or one track (track_), plays now, and is recorded when the+ * take records. nota_engine_note_expression(pitch -1, dim 0..3) keeps working and maps to+ * wheel / pressure / CC74 / CC64. */+NOTA_API NotaResult nota_engine_controller(NotaEngine* engine, int32_t ctl, float value);+NOTA_API NotaResult nota_track_controller(NotaEngine* engine, int32_t track_id, int32_t ctl, float value);++/* The last value delivered to the track's instrument for ctl (NaN = none): tests, meters. */+NOTA_API float nota_track_delivered_controller(const NotaEngine* engine, int32_t track_id, int32_t ctl);++/* Device-free self-test: curve value-at (step + linear), split/trim carry, chase value,+ * end-of-clip release, automation precedence, overdub touched-range fold. 0 = pass, else+ * the number of the first failed check. */+NOTA_API int32_t nota_engine_midi_ctl_selftest(NotaEngine* engine);+```++## Changes to existing functions++- **`nota_track_add_automation_lane(engine, track, target, device_index, param_index)`**+ accepts **target 5** (MIDI controller) with `device_index -1` and `param_index = ctl`.+ It refuses target 5 on non-instrument tracks and for reserved CCs. An existing lane on+ the same ctl is reused.+- **`nota_track_automation_lane_info`** reports target 5 with `param_index = ctl`.+- **`nota_track_begin_automation_write` / `end_…`** accept target 5. Hardware writes are+ started by the engine itself (research R7); the UI calls these only for mouse gestures+ on a drawn lane.+- **`nota_engine_note_expression` / `nota_track_note_expression` with pitch −1, dim 3+ (sustain)** now pass the value through unthresholded. Built-ins threshold at 0.5;+ plug-ins get `round(value*127)`.+- **Clip operations** (`nota_clip_split`, trim, join/consolidate, clipboard copy/paste,+ cross-track move, `nota_session_slot_to_arrangement`, arrangement → slot) carry+ controllers per [data-model.md](../data-model.md). Their signatures are unchanged.++## Smoke coverage (`tests/Nota.SmokeTest/MidiControllerTests.cs`)++1. **Selftest**: `nota_engine_midi_ctl_selftest() == 0`.+2. **Set/get round trip**: list / get / set, including removal and the refusal of reserved CCs; undo restores.+3. **Record**: arm, record, send CC64 down/up, a wheel ramp and CC1 through `nota_track_controller`, stop. The take holds the curves at the expected beats within one block, with thinned point counts.+4. **Playback**: `nota_track_delivered_controller` reads what reached the instrument. Clip playback delivers the values at the right beats.+5. **Chase**: start playback mid-clip; the first block delivers the value at that beat.+6. **End release**: a clip with the pedal down at its end, then transport stop. CC64 = 0 and wheel = 0 are delivered.+7. **Overdub fold**: a loop take, pass 2 moves CC1 over half the loop. Pass-1 points outside the touched range stay.+8. **Pedal-only pass in Replace mode**: notes stay, and CC64 is replaced over the touched range.+9. **Precedence**: a target-5 lane on CC1 overrides the clip's CC1.+10. **Persistence**: save → load keeps the curves and target-5 lanes; a v21 file loads with none.+11. **Poly aftertouch** (R11): 0xA0 on a non-MPE take lands in the note's pressure curve.diff --git a/specs/020-midi-cc-record-automate/contracts/instrument.md b/specs/020-midi-cc-record-automate/contracts/instrument.mdnew file mode 100644index 00000000..a2612d8a--- /dev/null+++ b/specs/020-midi-cc-record-automate/contracts/instrument.md@@ -0,0 +1,27 @@+# Contract: `Instrument::controller`++```cpp+// Instrument-wide MIDI controller (specs/020). ctl per NOTA_CTL_* (0..127 CC, 128 wheel,+// 129 channel pressure); value normalised. Audio thread, between render() calls, at a+// sample-accurate block offset (playEvents splits the render there). Default: the four+// controllers built-ins already understand go to noteExpression(-1, …); the rest are ignored.+virtual void controller(int32_t ctl, float value);+```++| Implementer | Behaviour |+|---|---|+| `Instrument` (default) | 128 → `noteExpression(-1, ExprBend, v)`; 129 → `(-1, ExprPressure, v)`; 74 → `(-1, ExprSlide, v)`; 64 → `(-1, ExprSustain, v)`; otherwise no-op |+| Built-ins with a `modwheel` parameter (BassSynth, OperatorSynth, Consort, any other found by parameter id) | 1 → set the Mod Wheel parameter to `v` (the same atomic write automation does), then the default |+| `RackInstrument` / `DrumRack` | forward `controller` to every chain's instrument |+| Plug-in host (`pluginhost/PluginHost.cpp`) | 0..127 → `controllerEvent(1, ctl, round(v*127))` (CC64 exact, not thresholded); 128 → `pitchWheel(1, round((v+1)*8191.5))`; 129 → `channelPressureChange(1, round(v*127))`. Overrides the default, so pitch −1 expression is not sent twice. |+| Keys / Physical (sustain) | unchanged: `ExprSustain` value ≥ 0.5 = down |++## Wire inside the engine++- **Dim encoding**: controllers travel as `ExprEv{off, pitch = -1, dim = kCtlDimBase + ctl, value}`+ with `kCtlDimBase = 16`, and as live `MidiEvent{expr = kCtlDimBase + ctl}`.+- **Dispatch**: `playEvents` sends `dim >= kCtlDimBase` to `controller()`; per-note dims+ still go to `noteExpression`.+- **Live expression**: `applyLiveExpression` does the same split.+- **Remote and gamepad**: pitch −1 dims 0–3 from `nota_*_note_expression` are rewritten to+ controllers 128 / 129 / 74 / 64 at enqueue, so one path handles everything.diff --git a/specs/020-midi-cc-record-automate/contracts/ui-lanes.md b/specs/020-midi-cc-record-automate/contracts/ui-lanes.mdnew file mode 100644index 00000000..6491315c--- /dev/null+++ b/specs/020-midi-cc-record-automate/contracts/ui-lanes.md@@ -0,0 +1,72 @@+# Contract: Controller lanes (piano roll) and the CC automation target++Follow [`DESIGN.md`](../../../DESIGN.md) (Studio) and the `nota-design` skill:+- sentence-case labels;+- neutral ink for curves and blocks;+- accent only for the point or block under the pointer and for the selection.++## Piano roll lane tabs++`Vel · Bend · Pres · Slide · <Controller>`++- **Fifth tab**: shows the current controller's short name: *Sustain*, *Mod wheel*,+ *Pitch wheel*, *Pressure*, *CC 11*, …+ - Default: *Sustain*, or the first controller with data in the clip.+ - The choice is remembered per clip editor session, like the lane mode.+- **Picker**: a click on the active fifth tab, or a small chevron beside it, opens a menu.+ - Controllers with data in this clip come first, each marked with the dot used by the+ automation picker.+ - Then Sustain (CC64), Mod wheel (CC1), Pitch wheel, Channel pressure, Expression (CC11)+ and Breath (CC2).+ - Then **Other CC ▸**, a submenu of 0–127 in groups of 16, "CC 7 — Volume" style.+ Reserved CCs are not listed.+- **Height**: the lane uses the MPE lane height (`ExprH`).++## Controller lane (clip-wide)++**Time axis**: the same as the notes, covering the whole clip. A pickup before the clip+start is drawn faintly left of the clip edge, like notes.++**Switch controllers (CC64–69)** are drawn as blocks:+- A block is a span where the value is ≥ 0.5. Partial values show as the block's fill+ height, so a half pedal draws a half-height block.+- **Drag on empty lane**: draws a new block (snaps to the grid; ⌘ or Ctrl turns snap off,+ as for notes).+- **Drag either edge**: resizes the block.+- **Drag the body**: moves the block.+- **Double-click a block or press Delete with it selected**: deletes the block.+- **Right-click**: *Clear Sustain* (the controller's name).++**Continuous controllers** are drawn as a curve with points:+- **Range lines**:+ - CC: 0–127, with a midline label.+ - Pitch wheel: centre line plus ±full travel, labelled "centre" and "+/−". Points within+ 2% of centre snap to exact 0.+- **Drag across the lane**: draws freehand. The drawn stretch replaces the points under+ it. ⌥ draws a straight line.+- **Points**:+ - Drag a point to move it in time (between its neighbours) and in value.+ - Double-click empty lane adds a point; double-click a point deletes it.+- **Right-click**: *Clear <name>*.++**Hover readout**: the value under the pointer in the controller's units ("64", "+0.42",+"on / off").++**Undo**: every gesture is one undo step (`nota_midi_clip_ctl_set` once on release; a live+preview during the drag uses the same call without a checkpoint if one exists, otherwise+the final set only).++**Selection and copy**: notes are unaffected by controller edits. Copying notes does not+copy controllers; copying the clip does.++## Arrangement automation target picker (instrument tracks)++- **Submenu**: a **MIDI controllers ▸** submenu sits after the instrument's parameters.+ Its list matches the piano-roll picker, minus the clip-data dots.+- **Dots**: the automated-target dot marks ctls that have a target-5 lane.+- **Lane label**: the short name ("Mod wheel", "CC 74").+- **Value range**: wheel −1..1 with a centre line; others 0..1, shown as 0–127.+- **Recording**: the existing behaviour. With Record engaged, moving the hardware+ controller writes the lane if it exists, latched until stop.+- **Clip data**: where a target-5 lane has points, the piano-roll lane for that+ controller shows a one-line note: "Track automation overrides this lane".diff --git a/specs/020-midi-cc-record-automate/data-model.md b/specs/020-midi-cc-record-automate/data-model.mdnew file mode 100644index 00000000..0167bf0e--- /dev/null+++ b/specs/020-midi-cc-record-automate/data-model.md@@ -0,0 +1,91 @@+# Data Model: Record and automate MIDI CC++## Controller id (`ctl`)++| ctl | Controller | Value range | Rest value | Interpolation |+|---|---|---|---|---|+| 0–127 | CC *n* | 0..1 (data / 127) | 0 (CC7 / CC11: none, no reset) | linear |+| 64–69 | Sustain, Portamento, Sostenuto, Soft, Legato, Hold 2 | 0..1, on at ≥ 0.5 | 0 | **step** (hold) |+| 128 | Pitch wheel | −1..+1 | 0 | linear |+| 129 | Channel pressure | 0..1 | 0 | linear |++The reserved CCs are never recorded or offered: 6, 38 and 96–101 (data entry, RPN/NRPN)+and 120–127 (channel mode). Their meaning is set by context, so storing them alone would+be wrong.++## ControllerCurve *(engine, immutable once published)*++| Field | Type | Notes |+|---|---|---|+| ctl | int32 | see table |+| points | vector<AutomationPoint> | sorted by beat, clip-local beats; may be < 0 (pickup before the clip start); `curve` honoured for linear ctls; at most one point per beat |++- **Value at a beat**: held after the last point. Step ctls take the value of the last+ point ≤ beat. Linear ctls interpolate with automation shaping.+- **Before the first point**: the curve has no value. Playback sends nothing there and the+ controller keeps whatever it had, so a pedal pressed on beat 1 is not down at the clip start.+- **Replace-range junctions**: a recorded range meets the old curve in a step. The old value+ holds to 1/1024 beat before the range (`kCtlJunction`), and the range's last value holds to+ 1/1024 beat before the old curve takes over again.+- **Empty curve**: never stored. Setting 0 points removes the curve.++## MidiClip (extended)++| Field | Change |+|---|---|+| controllers | **new** `vector<shared_ptr<const ControllerCurve>>`, at most one per ctl, sorted by ctl |++How clip operations treat controllers:+- **Move, copy, duplicate, cross-track move, clipboard**: travel with the clip by value of+ the vector, and the curves are shared.+- **Split at b**: each curve is cut. The left clip keeps points < b plus a point at b with+ the value there. The right clip gets a point at 0 with the value at b, then the rest+ shifted by −b.+- **Left trim / left-edge extend**: points shift with the clip start, like notes.+- **Join / consolidate**: curves are stitched per ctl. A gap inside the result gets the rest+ value when the source clip ended there.+- **Quantize**: no effect.+- **Session slot** clip (`SessionSlot::midi`): same field, loop-local beats in [0, L).++## Track (extended)++| Field | Change |+|---|---|+| automation lanes | target `MidiController = 5`, `deviceIndex = -1`, `paramIndex = ctl` |+| `Instrument::deliveredCtl[130]` *(audio-thread state, relaxed atomics, not persisted)* | last controller value delivered to the instrument (live, clip, later automation); NaN = none. It lives on the instrument rather than the `Track` because the instrument outlives graph snapshots. Used for the stop/seek release and read by `nota_track_delivered_controller` |++## Recording state *(engine)*++| Item | Thread | Shape |+|---|---|---|+| `RecordedCtl` queue | audio → message, SPSC `1 << 14` | `{ ctl, beat (absolute, or loop-local for slots), value, pass }` |+| live controller latest | MIDI/UI → message | `atomic<float> liveCtl_[130]`, `atomic<uint32_t> liveCtlTouch_[130]` |+| take ctl fold state | message | per ctl: pending raw points, last committed point, current replace range `[start, latest]`, pass of the range |++**Replace-range lifecycle** (per ctl, per take):+`idle` → first point of pass *p* → `open(start = beat)` → each fold removes old points in+[start, latest] and inserts the new ones → loop wrap closes the range at the loop end, and+record stop closes it at the stop beat with a junction point → `idle`.++## Persistence (format v22)++```text+MidiClipDto { …, Controllers?: ControllerCurveDto[] }+SessionSlotDto { …, Controllers?: ControllerCurveDto[] } // slot's MIDI clip+ControllerCurveDto { Ctl: int, Beats: double[], Values: float[], Curves?: float[] } // parallel arrays; Curves null when all linear; saved rounded to 1e-6 beat / 1e-4 value+AutomationLaneDto { Target: 5, DeviceIndex: -1, ParamIndex: ctl, Points } // existing DTO+```++- Loading v ≤ 21 means no controllers and no change.+- Unknown `Ctl` values (> 129) and reserved CCs are dropped with a load warning.++## Managed contracts++- `MidiController` static helper (Application): `PitchWheel = 128`, `ChannelPressure = 129`.+ It also provides `Name(ctl)` (standard CC names), `ShortName(ctl)`, `IsSwitch(ctl)`,+ `Range(ctl)` and `IsReserved(ctl)`.+- `AutomationTarget.MidiController = 5`.+- `IAudioEngine`: `GetMidiClipControllers(track, clip) → int[]` and+ `GetMidiClipController(track, clip, ctl) → NotaAutomationPoint[]`.+ `SetMidiClipController(…, points)` does the set, with 0 points meaning remove. The+ same calls exist for session slots, plus `SendController(track?, ctl, value)`.diff --git a/specs/020-midi-cc-record-automate/plan.md b/specs/020-midi-cc-record-automate/plan.mdnew file mode 100644index 00000000..61b35e95--- /dev/null+++ b/specs/020-midi-cc-record-automate/plan.md@@ -0,0 +1,157 @@+# Implementation Plan: Record and automate MIDI CC++**Branch**: `feat/midi-cc-record-automate` | **Date**: 2026-10-16 | **Spec**: [spec.md](spec.md)++**Input**: Feature specification from `/specs/020-midi-cc-record-automate/spec.md`++## Summary++MIDI clips gain **controller curves**: the sustain pedal, the pitch wheel, channel+pressure and any CC 0–127, one curve per controller, recorded with the notes and played+back to the instrument. The piano roll edits them in its lane under the notes. Track+automation gains a **MIDI controller** target, so a lane can drive any of them across clips.++The approach reuses what is already there. The data reuses the automation breakpoint+type. The live path reuses the instrument-wide expression channel (`pitch −1`). Playback+reuses the per-block expression stream (`ExprEv`) that already carries recorded MPE to+instruments, routed tracks and racks. Recording uses a new lock-free queue beside the+recorded-note one, and the message thread folds it into the take.++One new instrument entry point, `Instrument::controller(ctl, value)`, carries every+controller:+- Its default maps the four controllers the built-ins already understand (wheel,+ pressure, CC74, CC64) onto today's `noteExpression(-1, …)`.+- Built-ins with a *Mod Wheel* parameter take CC1.+- The plug-in host forwards the exact MIDI message.++The work lands as three PRs:+1. Recording and playback (engine, ABI, persistence).+2. Piano-roll lanes.+3. CC automation.++Details and rationale: [research.md](research.md).++## Nota: Read Before Planning++Consult the matching source of truth before designing:++- **Engine work** → [`ARCHITECTURE.md`](../../ARCHITECTURE.md): the AR rules table is binding (AR-4 lock-free queue, AR-5 immutable snapshots, AR-6 audio-thread restrictions, AR-7 pure C ABI, AR-9 `Transport` is the only source of musical time).+- **UI work** → [`DESIGN.md`](../../DESIGN.md) (Studio design language) and the `nota-design` skill.+- **Anything** → [`CONTRIBUTING.md`](../../CONTRIBUTING.md): licensing, dependency policy, PR expectations.++## Technical Context++**Language/Version**: C++20 (engine, plug-in host), C# / .NET 10 (managed app, Avalonia UI, MCP)++**Primary Dependencies**: None new. JUCE stays in `pluginhost/` and only gains a `controllerEvent` call for arbitrary CCs.++**Storage**:+- The project format goes from v21 to v22.+- MIDI clips and Session slot clips get an optional `Controllers` list: controller id plus breakpoints.+- Older projects load unchanged. An older Nota keeps the unknown field through `[JsonExtensionData]` and round-trips it on save, but does not play it.++**Audio-Thread Impact**:+- *Recording*: `drainLiveMidi` already coalesces live expression per block. Instrument-wide entries for the record track now also push a `RecordedCtl` into a new SPSC queue (`1 << 14`, AR-4/AR-6, no allocation).+- *Playback*: `gatherInstrumentNotes` and `renderSessionSlotRaw` append controller `ExprEv`s into the existing fixed `kMaxBlockExpr` buffer. Curves are `shared_ptr<const>` inside the immutable snapshot (AR-5) and are only read there.+- *Track automation*: `applyAutomation` sends a controller only when its value changed. The last sent value lives in a fixed per-track array on the audio side.+- Chasing and the end-of-clip release are branches on data already read.+- There are no locks, allocations or I/O anywhere on the audio thread.++**Testing**:+- A new `tests/Nota.SmokeTest/MidiControllerTests.cs` covers recording, playback, chase, end-of-clip release, overdub touched-range replace, ABI round-trip and save/load. It renders offline through the C ABI with a probe instrument.+- A device-free `nota_engine_midi_ctl_selftest` backs it.+- `scripts/build.sh` is the gate.+- UI checks use the headless recipe in [quickstart.md](quickstart.md).++**Target Platform**: macOS, Linux, Windows desktop.++**Project Type**: desktop app (native engine + managed UI).++**Performance Goals**:+- Controller timing on playback is within one audio buffer, and within 64 samples inside a block for moving curves, the same step as recorded MPE.+- 2 minutes of continuous wheel movement thins to well under 100 KB in the saved project (SC-005).++**Constraints**:+- Recording republishes the take on the existing poll cadence. Curves are shared and thinned incrementally, so cloning the track per poll does not copy large arrays.+- Live latency of controllers is unchanged.++**Scale/Scope**:+- Up to 130 controller ids per clip, typically 1–4 in use.+- Recorded points are thinned to the gesture: a few hundred for a 2-minute wheel take.++## Constitution Check++*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*++| Principle | Status | How |+|---|---|---|+| I. Real-time audio safety | ✅ | New SPSC queue for capture. Fixed buffers for playback. Immutable shared curves in the snapshot. Per-track last-sent array preallocated. No alloc, lock or I/O on the audio thread. |+| II. Boundary discipline | ✅ | All access goes through new `nota_midi_clip_ctl_*`, `nota_session_slot_ctl_*` and `nota_*_controller` functions in `nota_engine.h`, plus automation target 5. JUCE is touched only in `pluginhost/PluginHost.cpp`. |+| III. Licensing hygiene | ✅ | New files (`MidiController.h`, `MidiControllerTests.cs`, `PianoRollView.Controllers.cs`) carry the SPDX header. No new dependency. |+| IV. Verification gate | ✅ | Engine behaviour change → `MidiControllerTests.cs` and the selftest in the smoke run. |+| V. One logical change per PR | ✅ | Three PRs (US1, US2, US3), each green on its own. |+| VI. Docs in sync | ✅ | Each PR gets a CHANGELOG `[Unreleased]` entry, FEATURES.md updates (the "aren't recorded" sentence goes) and nota-docs: piano roll, recording, automation pages, EN + RU. No new shortcut is planned, so nota-shortcuts only needs a check. |+| VII. Spec-first | ✅ | spec → clarify → plan (this) → tasks. |+| VIII. Rules not weakened | ✅ | Nothing to justify. |++Post-design re-check: still all ✅ (see [data-model.md](data-model.md) and [contracts/](contracts/)).++## Project Structure++### Documentation (this feature)++```text+specs/020-midi-cc-record-automate/+├── plan.md # this file+├── research.md # decisions R1–R11+├── data-model.md # controller ids, curves, lanes, queues, DTOs+├── quickstart.md # how to verify each story+├── contracts/+│ ├── c-abi.md # new nota_engine.h surface+│ ├── instrument.md # Instrument::controller and who overrides it+│ └── ui-lanes.md # piano-roll lane + automation picker behaviour+└── tasks.md # /speckit-tasks+```++### Source Code (repository root)++```text+src/native/nota.engine/+├── include/nota/nota_engine.h # + NOTA_CTL_*, clip/slot ctl get/set/list, live controller, target 5, selftest+├── src/MidiController.h # NEW: ctl ids, ControllerCurve (value at beat, step vs linear), thinning+├── src/MidiClip.h # MidiClip::controllers+├── src/Instrument.h # virtual controller(ctl, value) with default mapping+├── src/NoteExpression.h # ExprEv dim for controllers (kCtlDimBase)+├── src/MpeInput.h # emit every CC / wheel / pressure as a controller on non-member channels+├── src/Automation.h # AutomationTarget::MidiController = 5+├── src/Engine.h # RecordedCtl queue, take ctl state, live ctl latest values, per-track last-sent+├── src/Engine_Render.cpp # capture in drainLiveMidi / routed; playback, chase, end release; poll() fold-in+├── src/Engine_Automation.cpp # applyAutomation target 5; precedence; hardware write latch+├── src/Engine_Tracks.cpp # split / trim / join / consolidate / clipboard carry controllers+├── src/Engine_Session.cpp # slot controllers, loop-wrap chase+├── src/Synth.h, BassSynth.h, OperatorSynth.h, Consort.h, VoltSynth.h, … # CC1 → Mod Wheel param where present+├── src/nota_engine_track.cpp, nota_engine_automation.cpp, nota_engine_session.cpp # ABI shims+└── pluginhost/PluginHost.cpp # controller(): exact CC / wheel / pressure to the plug-in++src/managed/+├── Nota.Application/Engine/EngineContracts.cs, IAudioEngine.cs # MidiController ids, AutomationTarget.MidiController+├── Nota.Infrastructure/Interop/NativeMethods.Tracks.cs, NotaEngine.Tracks.cs+├── Nota.Infrastructure/Persistence/ProjectModel.cs, ProjectService.cs, ProjectMigrations.cs # v22+├── Nota.App/PianoRollView.Expression.cs # lane tabs gain the controller tab+├── Nota.App/PianoRollView.Controllers.cs # NEW: clip-wide controller lane (curve + sustain blocks)+├── Nota.App/ClipEditorView.cs # host wiring (get/set, undo)+├── Nota.App/ArrangementView.Automation.cs # target picker: "MIDI controllers" submenu; ranges/labels+└── Nota.Mcp/Tools/MidiTools.cs, AutomationTools.cs # get/set clip controllers; midi_cc automation target++tests/Nota.SmokeTest/MidiControllerTests.cs # NEW+```++**Structure Decision**: The existing engine/managed split holds. Each story touches the+files below.+- **US1 (PR 1)**: engine, ABI, interop, persistence and smoke. It also includes the read side of the piano roll: no lane yet, but recorded data is saved and plays back.+- **US2 (PR 2)**: piano roll and clip MCP tools.+- **US3 (PR 3)**: automation target, picker, recording, MCP automation.++## Complexity Tracking++No constitution violations; nothing to justify.diff --git a/specs/020-midi-cc-record-automate/quickstart.md b/specs/020-midi-cc-record-automate/quickstart.mdnew file mode 100644index 00000000..b4ae76fe--- /dev/null+++ b/specs/020-midi-cc-record-automate/quickstart.md@@ -0,0 +1,78 @@+# Quickstart: verifying MIDI controller recording, editing and automation++## Prerequisites++- macOS dev setup per [`BUILD.md`](../../BUILD.md).+- Isolated data dir for manual runs: `NOTA_DATA_DIR=/tmp/nota-cc`. `HOME` does not isolate JUCE.+- Optional: a MIDI keyboard with a sustain pedal and wheels. Without one, use the MCP+ tools or the smoke test.++## Gate (every PR)++```bash+scripts/build.sh+```++This builds the engine and the app and runs `tests/Nota.SmokeTest`, which includes+`MidiControllerTests` (checks 1–11 in [contracts/c-abi.md](contracts/c-abi.md)). Expected+result: all green, no new dropouts in `TimingBudget`.++## PR 1 — record and play back (US1)++1. **Keys and the pedal**: create a track with Nota Keys, arm it and record 4 bars while+ pressing and releasing the sustain pedal on chords.+ - Play the clip back. Notes are held and released at the same places as played.+ - Start playback in the middle of a held-pedal stretch. The pedal is already down.+2. **Plug-in and wheels**: on a plug-in synth, ride the mod wheel and bend.+ - Playback reproduces both.+ - Stop mid-bend: the pitch returns to centre and no note hangs.+3. **Any CC**: send CC11 swells to a plug-in.+ - Live: the plug-in follows.+ - Recorded: playback follows.+4. **Loop Overdub**: loop 2 bars and record notes on pass 1. On pass 2, move only the mod+ wheel over the second bar.+ - Pass-1 mod wheel data in bar 1 stays.+ - The notes stay.+5. **Loop Replace**: on pass 3, press only the pedal. The notes stay and the pedal is+ replaced where you pressed it.+6. **Save and reopen**: the controllers are still there.+7. **Old project**: open a pre-v22 project. It loads unchanged.++## PR 2 — piano-roll lanes (US2)++Open the take in the clip editor.++1. **Sustain**: the fifth lane tab reads *Sustain*, and the blocks match the pedal.+ - Drag a block's right edge earlier, then play: the release is earlier.+ - Undo restores it.+2. **Picker**: pick *Mod wheel* and draw a rise (⌥ for a straight line). Playback follows.+3. **Empty controller**: pick **Other CC ▸ CC 74**, draw a sweep in an empty clip on a+ plug-in, and play.+4. **Picker order**: the picker lists the controllers that have data first, each with a+ dot.++Visual proof: the headless Avalonia render, or the env-guarded in-app capture recipe+(see the project's UI verify notes). Capture the Sustain blocks and a CC curve in Studio+Dark and Studio Light.++## PR 3 — CC automation (US3)++1. **Draw a lane**: on an instrument track, open the automation target picker and choose+ **MIDI controllers ▸ CC 74**. Draw a lane across two clips and play: the plug-in's+ cutoff follows across clips.+2. **Record a lane**: add a *Mod wheel* lane, engage Record, play and move the hardware+ mod wheel. The lane is written, latched until stop.+3. **Precedence**: on a clip that also has recorded mod wheel data, the lane wins where+ it has points. The piano-roll lane shows "Track automation overrides this lane".++## MCP smoke (no hardware)++The calls below are illustrative; the exact names are settled in tasks:++```text+set_clip_controller track=1 clip=0 ctl=64 points=[{beat:0,value:1},{beat:3.5,value:0}]+get_clip_controllers track=1 clip=0+add_automation_lane track=1 target=midi_cc ctl=1+```++Then play and confirm the effect by ear or through the plug-in's UI.diff --git a/specs/020-midi-cc-record-automate/research.md b/specs/020-midi-cc-record-automate/research.mdnew file mode 100644index 00000000..76282208--- /dev/null+++ b/specs/020-midi-cc-record-automate/research.md@@ -0,0 +1,255 @@+# Research: Record and automate MIDI CC++Findings from the code as of `develop` @ d724fb5, and the decisions they lead to.++## What the code does today++- **Live decode** (`MpeInput.h`): on a non-member (ordinary or master) channel the wheel,+ channel pressure and CC74 become `mpeExpression(-1, dim)`. CC64 becomes+ `mpeExpression(-1, ExprSustain, 0|1)`, **thresholded at 64**. Every other CC is+ dropped, **CC1 included**. Poly aftertouch (0xA0) becomes per-note pressure on any channel.+- **MIDI Learn** (`Engine.cpp` ~L104): every CC is copied to `midiControl_` **in addition+ to** the MPE decode, so a learned CC already reaches both. The clarification "Learn CC is+ also recorded and passed on" needs no change to MIDI Learn.+- **Instruments**:+ - `Instrument::noteExpression(pitch, dim, value)`. Built-ins handle dims 0–2, and Keys+ and Physical handle dim 3 (sustain).+ - `RackInstrument` (and therefore `DrumRack`) forwards to every chain.+ - `PluginHost.cpp` turns pitch −1 into pitch wheel, channel pressure, CC74 and CC64+ (`value >= 0.5 ? 127 : 0`), always on channel 1.+- **Mod wheel on built-ins** is a *parameter*, not a controller: `ModWheel` in BassSynth,+ OperatorSynth, Consort (also a mod-matrix source) and others, reachable only by MIDI+ Learn or automation.+- **Recorded MPE**: `captureLiveExpr` records per-note dims for notes being captured;+ instrument-wide entries are skipped. `RecordedExprQueue` goes to `pendingExpr_` and then+ to `attachRecordedExpr`, which thins with RDP (`thinExprCurve`). Playback goes through+ `noteExprEvents` into `ExprEv{off, pitch, dim, value}` every 64 samples while moving,+ merged with note events in `playEvents`.+- **Routing**: `computeBlockMidi` fills `blockExpr_` per track. A "MIDI In" destination+ merges its source's `blockExpr_` in `renderInstrumentRaw`, so anything in the `ExprEv`+ stream reaches routed instruments for free.+- **Clip model**: `MidiClip` has notes plus `velocityEnvelope` and `volumeEnvelope`+ (`AutomationLane`). It is copied by value in `cloneTrack`, which is how undo works.+- **Automation**: `AutomationTarget` 0–4. `applyAutomation` runs per block on the audio+ thread. Writing goes through `beginAutomationWrite` / `sampleAutomationWritesAt` on the+ message thread, latched for hardware controls.+- **Recording fold-in** happens in `Engine::poll()` (message thread):+ - Notes move the clip's left edge back for pickups.+ - Replace mode removes earlier-pass notes. A pass replace is triggered only by a fresh+ **note** (`triggerPassReplace`).+- **Persistence**: C# `ProjectService` at format v21. Clip envelopes go through+ `GetMidiClipEnvelope` and `SetMidiClipEnvelope`.++## Decisions++### R1 — One controller id space++**Decision**: `ctl` 0–127 = that CC; 128 = pitch wheel; 129 = channel pressure+(`NOTA_CTL_PITCH_WHEEL`, `NOTA_CTL_CHANNEL_PRESSURE`). Values are normalised:+- CC: 0..1 (data / 127).+- Wheel: −1..+1 (centre 0).+- Pressure: 0..1.++**Rationale**: one integer addresses every controller in the clip, the ABI, automation+(`paramIndex`) and the UI picker. The wheel and pressure are not CCs in MIDI, but users+treat them as controllers.++**Alternatives**: separate enums per kind (more ABI surface); raw 14-bit / 7-bit integers+(pushes MIDI encoding into the UI).++### R2 — `Instrument::controller(ctl, value)` as the single entry point++**Decision**: add `virtual void controller(int32_t ctl, float value)` to `Instrument`.+- **Default**: wheel → `noteExpression(-1, ExprBend, v)`, pressure → `(-1, ExprPressure)`,+ CC74 → `(-1, ExprSlide)`, CC64 → `(-1, ExprSustain, v)`. Built-ins and racks keep+ working unchanged.+- **RackInstrument**: forwards `controller` to its chains.+- **PluginHost**: overrides it and sends the exact message (14-bit wheel, 7-bit CC,+ channel pressure). CC64 keeps its real value.+- **Built-ins with a `modwheel` parameter**: map CC1 to it.+- **Sustain** becomes continuous 0..1 on the wire. Instruments already threshold at 0.5+ (`Keys.h` L191), so half-pedal values reach plug-ins intact and built-ins see on/off.++**Rationale**: FR-003 (plug-ins get all controllers, built-ins act on what they+understand) and the clarification that half-pedal values are kept. The issue explicitly+names CC1 for built-ins, and the existing *Mod Wheel* parameters are the natural target.++**Alternatives**: more `ExprDim` values (bloats `VoiceExpr` and per-note arrays); CC1 as a+new voice-level modulation in every synth (out of scope, see spec Assumptions).++### R3 — Live decode emits controllers++**Decision**:+- `MpeInput::Sink` gains `mpeController(ctl, value)`. On non-member channels the wheel,+ pressure and **every** CC (except RPN/NRPN/data-entry 6/38/98–101 and channel-mode+ 120–127) go there.+- CC64 goes there on any channel, as today.+- Per-note member-channel behaviour is unchanged.+- The engine carries live controllers as `MidiEvent{expr = kCtlDimBase + ctl, pitch = -1}`+ through the existing coalescing in `drainLiveMidi`.+- `nota_engine_note_expression(-1, dim)` (Remote, gamepad) maps to the same controllers.++**Rationale**: FR-004 (all CCs live to plug-ins). Recording and live use one path, and+coalescing per (track, ctl) keeps a streaming wheel from backing up the queue.++### R4 — Clip storage: shared immutable curves++**Decision**: `MidiClip::controllers` is a small vector of+`shared_ptr<const ControllerCurve>`; each curve is `{ ctl, std::vector<AutomationPoint> }`.+- Times are clip-local beats. They may be negative for pickups, like notes (spec 017).+- **Switch controllers** (CC64–69) hold their value until the next point (step). Every+ other controller is linear between points, and `curve` shaping is honoured as in+ automation.+- **Before the first point** the curve has no value: playback sends nothing, and the+ controller keeps what it had. A pedal pressed on beat 1 is not down at the clip start.+- **Playback placement**: recorded points sit on block starts, because capture is+ block-timed. Each point is placed on a whole sample with 1e-6 sample of slack, and the+ clip-entry check has half a sample of slack. Floating-point noise could otherwise drop+ a point between two blocks (found in PR 1 by the Session slot test).++**Rationale**: `cloneTrack` runs on every recording poll and every edit. Sharing curves+makes a clone O(curves), not O(points). `AutomationPoint` is already on the ABI+(`NotaAutomationPoint`), so get/set needs no new struct. Step semantics give exact sustain+blocks.++**Alternatives**: `AutomationLane` by value (copied per poll, which is too heavy for+recorded streams); per-note storage (wrong for instrument-wide data).++### R5 — Recording: capture queue, incremental thinning, touched-range replace++**Decision**:+- **Audio thread**: when `rec && timed`, each coalesced instrument-wide controller for the+ record track pushes `RecordedCtl{ctl, absBeat, value, pass}`. Session takes use+ loop-local beats, as notes do.+- **Take start**: controllers whose current live value is off rest (pedal down, wheel off+ centre, any CC already touched) are seeded at the take's first moment, so a held pedal+ is recorded.+- **Routed capture**: `renderInstrumentRaw` with `captureRouted` also records the+ source's controller `ExprEv`s.+- **Message thread (`poll`)**:+ - Per ctl, the pending raw points are folded into the take clip. Switch controllers are+ de-duplicated. Linear ones are RDP-thinned with the tolerances below, anchored on the+ last committed point, so the take stays editable while it grows.+ - The clip's left-edge move for pickups shifts controller points along with notes.+- **Replacement rule (clarifications 1–2)**:+ - In Overdub, and in a pass without notes in either mode, the first point of `ctl` in+ pass *p* opens a replace range at its beat.+ - Each fold removes existing points of `ctl` in `[rangeStart, latestBeat]` and inserts+ the new ones.+ - At pass end (loop wrap) the range closes at the loop end. On record stop (no loop) it+ closes at the stop beat with a junction point that restores the old curve's value+ there.+ - Controllers never call `triggerPassReplace`, so a pedal-only pass in Replace mode+ keeps the notes.+ - In Replace mode, once notes trigger a pass replace, the earlier passes' controller+ points for this take are removed too: the whole pass is replaced.+- **Thinning tolerances** (settled in PR 1): 0.008 for CC and pressure (about one 7-bit+ step), 0.012 for the wheel (about 1% of its travel). Capture is block-timed, so finer+ tolerances only kept the block grid's jitter: a 41-step ramp kept 25 points at+ 0.002 and keeps 2 now.+- **Junctions**: a replaced range meets the old curve in a step. The old value holds to+ `kCtlJunction` (1/1024 beat) before the range. At a close with old points after it, the+ range's last value holds to `kCtlJunction` before the close point.+- **Held-back tail**: a poll's run is thinned with the range's last committed point as+ the anchor. For a moving (linear) controller, the last thinned segment stays pending+ until the next poll, so thinning spans polls. The tail is committed in full at a range's+ end, at record stop and when a take ends otherwise (`flushCtlTake`: Session slot+ finalise, disarm). It is also capped at 512 points. Without this, every ~30 Hz poll kept+ a point: a 2-minute wobble was 7,502 points, and is 1,690 with it.++**Rationale**: FR-002, FR-009, FR-021 and SC-005.++**Alternatives**: thin only at record stop (the live take would hold raw block-rate+points, and every poll's clone and republish would grow); merge passes (rejected in+clarify).++### R6 — Playback: controllers ride `ExprEv`++**Decision**:+- **Events**: in `gatherInstrumentNotes` (arrangement) and `renderSessionSlotRaw`, each+ active clip's curves emit `ExprEv{off, -1, kCtlDimBase + ctl, value}`:+ - at each point inside the block;+ - every 64 samples while a linear curve moves;+ - at offset 0 on `chaseNotes_` (play start, jump, loop wrap) and when the playhead+ enters the clip, with the value at that beat.+- **Dispatch**: `playEvents` sends dims ≥ `kCtlDimBase` to `inst.controller()`.+- **End of clip (FR-006)**: when a clip that moved CC64 or the wheel ends, or the transport+ stops, the engine sends CC64 = 0 and wheel = 0. On stop it sends them to every+ instrument whose last sent value is off rest. The reset sorts ahead of a following+ clip's chase at the same offset.+- **Precedence (clarification)**: a ctl that has a track automation lane with points is+ skipped in clip emission.+- **Routed instruments, racks and Drum Racks**: get controllers through the existing+ `blockExpr_` merge and `RackInstrument::controller`.++**Rationale**: no new buffers or merge logic; timing matches recorded MPE.++### R7 — Track automation target `MidiController = 5`++**Decision**:+- **Lane shape**: `AutomationTarget::MidiController` with `paramIndex = ctl`. Values use+ the controller's own range (wheel −1..1, others 0..1).+- **Playback**: `applyAutomation` sends `instrument->controller(ctl, v)` only when it+ differs from a per-track `lastCtl_[130]`, which is preallocated, NaN-initialised and+ reset on track clone.+- **Recording**:+ - The MIDI thread stores each live controller's latest value and a touch counter in+ fixed atomics.+ - `poll()` starts a latched `beginAutomationWrite(track, 5, -1, ctl)` when automation+ record is on, the transport rolls, and the armed record track has a lane for that ctl.+ - `currentTargetValue` reads the latest live value.+ - While a lane exists for a ctl, the take does not capture that ctl into the clip:+ automation wins.+- **Scope**: instrument tracks only.++**Rationale**: FR-014–017; reuses M9-C writing and the existing lane editing and undo.++### R8 — C ABI surface++See [contracts/c-abi.md](contracts/c-abi.md). It covers:+- clip and slot controller list, get and set (set with 0 points removes the curve; one+ undo step);+- live `nota_engine_controller` / `nota_track_controller`;+- target 5 on the existing automation functions;+- `nota_engine_midi_ctl_selftest`.++### R9 — Persistence v22++**Decision**:+- `MidiClipDto.Controllers` and the Session slot clip DTO each get+ `ControllerCurveDto[]?`. A `ControllerCurveDto` is `{ int Ctl, double[] Beats, float[] Values,+ float[]? Curves }`: parallel arrays, with `Curves` null when every segment is linear.+ Values are rounded on save to 1e-6 beat and 1e-4 value. An object per point (`AutomationPointDto`)+ cost about 150 bytes each: a 2-minute wobble grew the project by 244 KB that way, and by+ 84.5 KB as arrays (SC-005).+- Automation lanes with target 5 save through the existing `AutomationLaneDto`+ (`ParamIndex = ctl`).+- No migration is needed: absent means none. The format constant goes to 22. The DTOs carry `[JsonExtensionData]`, so an older Nota keeps the field when it re-saves.++### R10 — UI++**Piano roll** (see [contracts/ui-lanes.md](contracts/ui-lanes.md)):+- A fifth lane tab shows the chosen controller's short name (default "Sustain"). Clicking+ it opens a picker:+ - Sustain, Mod wheel, Pitch wheel, Channel pressure, Expression (CC11);+ - "Other CC" with all 0–127 by number and the standard name;+ - controllers with data marked with a dot and listed first, the same affordance as the+ automation picker.+- The lane is clip-wide, drawn over the whole clip, not per note:+ - switch controllers as blocks;+ - others as a curve with points.+- Edits use the same gestures as the MPE lanes and reuse the arrangement automation+ drawing helpers. Each gesture is one undo step through `nota_midi_clip_ctl_set`.++**Automation picker**: a "MIDI controllers" submenu on instrument tracks, with the same+list and dots.++Studio rules apply: sentence-case labels, neutral ink, accent only for the hot point or+selection.++### R11 — Already satisfied: poly aftertouch++`MpeInput` already turns 0xA0 into per-note pressure on any channel, and `captureLiveExpr`+already records per-note dims for captured notes. So poly aftertouch from a non-MPE+keyboard is already stored as each note's pressure. The plan adds a smoke check, and a+FEATURES/docs wording fix if needed, instead of new code.diff --git a/specs/020-midi-cc-record-automate/spec.md b/specs/020-midi-cc-record-automate/spec.mdnew file mode 100644index 00000000..2191e3b5--- /dev/null+++ b/specs/020-midi-cc-record-automate/spec.md@@ -0,0 +1,230 @@+# Feature Specification: Record and automate MIDI CC++**Feature Branch**: `feat/midi-cc-record-automate`++**Created**: 2026-10-16++**Status**: Draft++**Input**: User description: "GitHub issue nota-daw/nota#69 — Record and automate MIDI CC: sustain pedal, pitch wheel, mod wheel, any CC. Goal: record a piano part with the sustain pedal, or a synth line with mod wheel and pitch wheel moves, have them play back from the clip, and draw or edit them afterwards. Requested: record incoming CCs (CC64 sustain, CC1 mod wheel, pitch wheel, channel pressure, any CC) into the MIDI clip along with the notes; edit them in the piano roll — CC lanes under the notes (next to VEL / Bend / Pres / Slide), with a picker for the CC number, the sustain pedal drawn as on/off blocks; automate them — CC as an automation target on instrument tracks (arrangement lanes), so a plug-in or built-in instrument receives the CC from automation; playback sends the CC to the instrument (built-in instruments that understand CC64 / CC1, and hosted plug-ins). Today: live input already reaches instruments (wheel, channel pressure, poly aftertouch, CC64 to plug-ins and Nota Keys). Recording keeps only per-note bend, pressure and slide (MPE); the pitch wheel, channel pressure and sustain pedal aren't recorded, and other CCs are neither recorded nor automatable. Automation lanes target device and mixer parameters only."++## Nota Context *(fill in — drives plan and tasks)*++**Feature area** *(pick the main one)*:++- [x] Engine (C++, `src/native/nota.engine`) — real-time audio rules apply, see `ARCHITECTURE.md` AR table+- [x] Managed app (C#, `src/managed/*`) — domain, application, infrastructure, presentation+- [x] UI (Avalonia, `src/managed/Nota.Presentation`) — follow `DESIGN.md` (Studio)+- [x] Plugin hosting (`pluginhost/`) — the only place JUCE is allowed+- [ ] Build / packaging / CI (`scripts/`, `.github/`) — see `BUILD.md`+- [ ] Docs only++What exists today, and what this feature builds on:++- **Live controllers.** Instrument-wide controls already reach instruments live through+ `nota_engine_note_expression` / `nota_track_note_expression` with `pitch = -1`+ (`nota_engine.h`): dim 0 the wheel (normalised −1..+1), 1 channel pressure, 2 slide+ (CC74), 3 the sustain pedal (CC64, 0/1). Hosted plug-ins get the wheel, channel pressure,+ poly aftertouch and CC64; other CC numbers are not passed on. The MPE decoder lives in+ `MidiInput.h`; built-ins that read CC64 / the wheel are listed in `FEATURES.md` (Keys,+ Physical, Pentad's mod wheel, Volt's vibrato, …).+- **Recorded expression.** Per-note MPE is stored per note (`NotaNoteData.expr_id` →+ `nota_note_expr_*`) and drawn in the piano roll's VEL / BEND / PRES / SLIDE lane. There+ is no clip-level (instrument-wide) controller data yet; MIDI clips only carry velocity and+ volume envelopes (`nota_midi_clip_env_*`, kind 0/1).+- **Track automation.** Lanes target track volume (0), pan (1), a built-in device+ parameter (2) or a plug-in parameter (3, by stable param id) — no MIDI CC target.+ Automation record is driven by the transport Record button (M9-C).+- **MIDI Learn.** `nota_midi_poll_control_events` drains incoming CCs for MIDI Learn+ (`MidiLearnService.cs`); a learned CC moves a mapped parameter.+- **Recording.** Live and routed ("MIDI In") capture, count-in pickups, loop Overdub /+ Replace and held-note preview (specs 017, 018) define where recorded notes land; recorded+ controllers must follow the same rules.++**Nota docs to keep in mind** *(links relative to `specs/<slug>/`, where this file lands)*:+[`ARCHITECTURE.md`](../../ARCHITECTURE.md) (AR rules),+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) (licensing, dependency policy, PR+expectations), [`BUILD.md`](../../BUILD.md), [`DESIGN.md`](../../DESIGN.md),+[`FEATURES.md`](../../FEATURES.md).++## Clarifications++### Session 2026-10-16++- Q: When a CC automation lane and clip controller data address the same controller at the same time, which does the instrument follow? → A: The track automation lane; the clip's data for that controller is ignored wherever the lane has points.+- Q: Is a CC bound by MIDI Learn also recorded into the clip and sent to the instrument? → A: Yes — it drives its mapped parameter and is also recorded and passed to the instrument.+- Q: Scope? → A: One spec for recording/playback, piano-roll lanes and CC automation, landed as three pull requests in priority order (Story 1, 2, 3).+- Q: In loop Overdub, what happens to a controller's earlier data when a later pass moves it? → A: The new pass replaces that controller's data over the range it touched (from its first move in the pass to the pass end); other controllers and untouched ranges stay.+- Q: Does a pass with only controller moves and no notes count as a played pass? → A: It replaces only the controllers it moved, over their touched range; notes stay (in Replace mode too).+- Q: Is the sustain pedal stored as on/off or with its 0–127 value? → A: Its full 0–127 value is stored; the lane draws on/off blocks by the ≥ 64 threshold and shows partial (half-pedal) values; plug-ins get the exact value, built-ins treat ≥ 64 as down.+- Q: Do arrangement clips / Session slots draw controller data? → A: No — piano roll only; arrangement clips and slots draw notes as today.+- Q: Is polyphonic aftertouch from a non-MPE keyboard recorded? → A: Yes, as each note's pressure (the same per-note expression MPE records), shown and edited in the PRES lane.++## User Scenarios & Testing *(mandatory)*++### User Story 1 - Record the sustain pedal, wheels and CCs with the notes (Priority: P1)++A pianist arms a track with Nota Keys (or a piano plug-in), records a passage using the+sustain pedal, and plays it back: the pedal holds the notes exactly as it did while+playing. A synth player records a line while riding the mod wheel and bending with the+pitch wheel; playback reproduces the vibrato and the bends. A user with a controller that+sends expression (CC11) or a breath controller (CC2) into a plug-in gets those moves back+too.++**Why this priority**: This is the core gap in the issue. Without recording, a performance+with the pedal or wheels cannot be captured at all; editing and automation build on the+recorded data.++**Independent Test**: Record a short phrase with the pedal pressed and released a few+times, the mod wheel moved and one pitch bend; play the clip back and compare by ear and by+the instrument's response with the live take (Keys' notes held/released at the same beats,+the plug-in's mod/bend indicators moving the same way).++**Acceptance Scenarios**:++1. **Given** an armed instrument track and recording running, **When** the player presses and releases the sustain pedal, **Then** the pedal presses and releases are stored in the take at the beats they happened and play back to the instrument at those beats.+2. **Given** recording, **When** the player moves the pitch wheel, mod wheel (CC1) or channel pressure, **Then** the moves are stored in the take and play back to the instrument with the same shape and timing.+3. **Given** recording into a track with a hosted plug-in, **When** the controller sends any other CC number, **Then** that CC is stored and plays back to the plug-in; while playing live, the plug-in receives it as well.+4. **Given** a recorded take with controller data, **When** the clip is moved, copied, split, looped or quantized, **Then** its controller data moves, copies, splits and loops with it (quantize moves notes only), and the project saves and reloads it.+5. **Given** playback starts in the middle of a clip, **When** a controller had already been moved earlier in the clip, **Then** the instrument first receives that controller's value at the start position (e.g. the pedal is already down, the mod wheel already up).+6. **Given** a clip whose sustain pedal is down at the clip's end (or playback stops), **When** the clip ends or the transport stops, **Then** the pedal is released and the wheel returns to centre — no note stays held.+7. **Given** loop recording in Overdub or Replace mode, a count-in pickup, or recording into a Session slot, **When** controllers are moved, **Then** they land in the take by the same rules as the notes (pickups are kept before the record start); in Overdub, and in a pass with no notes in either mode, a pass replaces each controller it moved over the range it touched, leaving other controllers and the notes alone (FR-021).+8. **Given** an ordinary (non-MPE) keyboard that sends polyphonic aftertouch, **When** the player records, **Then** each note's aftertouch is stored as that note's pressure and plays back the same way.++---++### User Story 2 - See and edit controller lanes in the piano roll (Priority: P2)++After recording, the user opens the clip in the piano roll and picks the sustain pedal in+the lane under the notes: the pedal shows as on/off blocks, and they drag a block's edge to+release the pedal earlier before a chord change. They switch the lane to the mod wheel and+redraw a smoother rise; they pick "CC 11" from the lane's picker and draw an expression+swell into an empty clip.++**Why this priority**: Recording is useful on its own; editing turns a good take into a+finished one and lets users draw controllers without a hardware controller.++**Independent Test**: In a clip with and without recorded controllers, switch the lane to+Sustain, Pitch wheel, Mod wheel, Channel pressure and an arbitrary CC; draw, move and delete+values; undo each step; play back and confirm the instrument follows the edited data.++**Acceptance Scenarios**:++1. **Given** the piano roll's lane picker, **When** the user opens it, **Then** it offers, next to VEL / BEND / PRES / SLIDE, Sustain (CC64), Pitch wheel, Mod wheel (CC1), Channel pressure and any CC number 0–127, and the controllers that already hold data in this clip are marked and listed first.+2. **Given** the Sustain lane, **When** it is shown, **Then** the pedal is drawn as on/off blocks (down where the value is ≥ 64), with partial (half-pedal) values visible; the user can draw a block, drag either edge, or delete it.+3. **Given** a continuous lane (pitch wheel, mod wheel, channel pressure, any other CC), **When** the user drags across the lane, **Then** values are drawn along the drag (⌥ for a straight line, like the MPE lanes), points can be moved and added/deleted with a double-click, and right-click offers clearing the lane.+4. **Given** any controller edit, **When** it is made, **Then** it is one undo step and plays back straight away.+5. **Given** the pitch wheel lane, **When** it is shown, **Then** its scale shows centre and the wheel's full up/down travel, and drawn values snap back to exact centre near the middle.++---++### User Story 3 - Automate a CC on an instrument track (Priority: P3)++A user wants a slow filter sweep on a plug-in that only exposes it through CC74 (or wants+the mod wheel up for the whole chorus regardless of clip). They open the automation target+picker on the instrument track, choose MIDI CC → "CC 74", and draw the lane in the+arrangement; the instrument receives the CC as the song plays, across clips.++**Why this priority**: Automation is a separate path from clips and is requested last in+the issue; it reuses the track automation lanes users already know.++**Independent Test**: On an instrument track, add a CC automation lane (pitch wheel,+sustain, CC1, CC74), draw it, play the song and confirm the instrument receives the values;+record it by moving the controller with transport Record engaged.++**Acceptance Scenarios**:++1. **Given** an instrument track's automation target picker, **When** the user opens it, **Then** it offers MIDI controllers — Pitch wheel, Channel pressure, Sustain (CC64), Mod wheel (CC1) and any CC 0–127 — alongside device and mixer parameters.+2. **Given** a CC automation lane, **When** the song plays, **Then** the instrument (built-in or plug-in) receives the lane's values as that controller.+3. **Given** a CC automation lane and the transport Record button engaged, **When** the user moves that controller on the hardware, **Then** the lane is written the same way other automation is recorded.+4. **Given** a track with both a CC automation lane and clip data for the same controller, **When** they overlap in time, **Then** the instrument follows the track automation lane; the clip's data for that controller is ignored wherever the lane has points.++---++### Edge Cases++- A CC that is bound by MIDI Learn to a parameter: it still moves its mapped parameter (and writes that parameter's automation with Record engaged) and is also recorded into the clip and passed to the instrument (FR-020).+- MPE controller: per-note bend / pressure / slide on member channels stay per-note (unchanged); only the master channel's wheel, pressure and CCs become clip controller data.+- Controllers moved while nothing is recording or armed: no data is stored; live behaviour is unchanged.+- A dense controller stream (a fast wheel wiggle, a breath controller sending hundreds of messages per second): recorded faithfully enough to sound the same, without bloating the project; repeated identical values are not stored.+- Two overlapping clips on the same track, or a clip shorter than its pedal press: playback releases the pedal at the clip's end so no note is stuck.+- A clip moved to a track with a different instrument: controller data travels with the clip; an instrument that ignores a controller simply ignores it.+- Built-in instruments that do not understand a given CC (e.g. CC11 on Nota Synth): the data is kept and drawn, the instrument ignores it; no error.+- An Instrument Rack: controller data reaches every chain, like live input today.+- Drum Rack: controller data reaches every pad's instrument.+- A Session slot loops: controller state at the loop end is reset/chased at the loop start the same way it is at a clip start.+- Old projects open unchanged; a project saved with controller data and opened in an older Nota plays without it (the data is kept in the file).++## Requirements *(mandatory)*++### Functional Requirements++**Recording and playback (Story 1)**++- **FR-001**: While recording MIDI onto a track, the system MUST store in the take the sustain pedal (CC64), pitch wheel, channel pressure, mod wheel (CC1) and every other CC number 0–127 received from the input that feeds the track, at the beats they were received.+- **FR-002**: Recorded controllers MUST follow the same capture rules as notes: live and routed ("MIDI In") input, count-in pickups, loop Overdub / Replace, Session slot recording, and track-addressed input (Nota Remote, gamepad) where those send controllers.+- **FR-003**: Playback of a clip MUST send its controller data to the track's instrument — built-in instruments (each acting on the controllers it understands) and hosted plug-ins (all controllers) — at the stored beats, including inside Instrument and Drum Racks.+- **FR-004**: Live input MUST pass every CC number (not only CC64) to hosted plug-ins, so what is recorded matches what the player heard.+- **FR-005**: When playback starts or jumps inside a clip, or a looped clip/slot wraps, each controller with data in the clip MUST first be set to its value at that position (chasing).+- **FR-006**: When a clip ends, playback stops, or the playhead leaves the clip, the sustain pedal MUST be released and the pitch wheel returned to centre if the clip had moved them; no note may stay held because of recorded controller data.+- **FR-007**: Controller data MUST travel with the clip on move, copy, duplicate, split, trim, loop and cross-track moves, and MUST be saved with and restored from the project. Quantize MUST NOT move controller data.+- **FR-008**: Per-note MPE expression on member channels MUST stay per-note as today; clip controller data comes from the master channel / non-MPE input only. Polyphonic aftertouch from a non-MPE input MUST be recorded as each note's pressure, the same per-note expression MPE records.+- **FR-009**: Recording MUST store controller data compactly: unchanged repeated values are not stored, and a continuous move keeps its audible shape.++**Editing (Story 2)**++- **FR-010**: The piano roll's lane under the notes MUST offer Sustain, Pitch wheel, Mod wheel, Channel pressure and any CC number 0–127 next to VEL / BEND / PRES / SLIDE; controllers holding data in the clip MUST be marked and sorted first.+- **FR-011**: The Sustain lane (and any CC the user switches to on/off display) MUST draw the controller as on/off blocks (on at ≥ 64) that can be drawn, resized by either edge and deleted; stored values keep their full 0–127 range and partial values are shown.+- **FR-012**: Continuous controller lanes MUST support drawing along a drag, straight lines with ⌥, moving points, double-click to add/delete, and right-click clear, consistent with the MPE lanes.+- **FR-013**: Every controller edit MUST be one undo step and MUST be heard on the next playback pass without re-opening the clip.++**Automation (Story 3)**++- **FR-014**: Track automation on instrument tracks MUST offer MIDI controllers as targets — Pitch wheel, Channel pressure, Sustain, Mod wheel and any CC 0–127 — with the same lane drawing, selection, paste and undo as existing automation targets.+- **FR-015**: During playback a CC automation lane MUST send its values to the track's instrument as that controller.+- **FR-016**: With transport Record engaged, moving a hardware controller that has a CC automation lane on the armed/selected track MUST record into that lane like other automation recording.+- **FR-017**: When a CC automation lane and clip controller data address the same controller at the same time, the instrument MUST follow the automation lane; the clip's data for that controller is ignored wherever the lane has points.++**Engine interface**++- **FR-018**: Clip controller data and CC automation targets MUST be readable and writable through the public engine interface, so the app, MCP tools and other front-ends can use them; recording, playback, chasing and the end-of-clip release MUST be covered by the engine smoke test.+- **FR-019**: Recording and playback of controllers MUST NOT allocate, lock or do I/O on the audio thread.+- **FR-020**: A CC bound by MIDI Learn MUST keep driving its mapped parameter as today and MUST also be recorded into the take and passed to the instrument like any other CC.+- **FR-021**: In loop Overdub, and in any pass that contains no notes, a pass MUST replace each controller it moved over the range it touched (from its first move in the pass to the pass end); controllers it did not move, untouched ranges, and the take's notes MUST stay.+- **FR-022**: Controller data is shown only in the piano roll; arrangement clips and Session slots draw notes as today.++### Key Entities++- **Clip controller data**: per MIDI clip, a set of controller curves, each identified by its controller (Sustain, Pitch wheel, Channel pressure, CC n). A curve is a list of points (clip-local beat, value); the sustain pedal and other switch-like controllers hold on/off steps. Travels with the clip.+- **CC automation lane**: a track automation lane whose target is a MIDI controller instead of a device or mixer parameter; values in the controller's own range.+- **Controller identity**: Pitch wheel (centre-relative, full up/down travel), Channel pressure (0..1), CC 0–127 (0..127 always stored in full; switch controllers such as CC64 are drawn as on/off at ≥ 64).++## Success Criteria *(mandatory)*++### Measurable Outcomes++- **SC-001**: A recorded take with sustain pedal, mod wheel and pitch wheel plays back so that every pedal press/release and wheel move lands within one audio buffer of where it was played, for 100% of the events in a 2-minute test take.+- **SC-002**: Starting playback at 10 random positions inside a clip with recorded pedal and mod wheel, the instrument's pedal and wheel state match the clip's state at that position every time.+- **SC-003**: After any clip end, stop or jump, no note stays sounding because of a recorded pedal (0 stuck notes in a 50-stop test).+- **SC-004**: A user can switch the piano-roll lane to the sustain pedal and shorten one pedal block in under 10 seconds, without reading documentation.+- **SC-005**: Recording 2 minutes of continuous wheel movement adds no new audio dropouts and grows the saved project by no more than 100 KB.+- **SC-006**: A CC automation lane drawn on a plug-in's instrument track moves the plug-in's mapped control audibly and visibly, matching the drawn curve within one audio buffer.++## Assumptions++- All controllers are recorded regardless of channel on a non-MPE input (channel is not kept); a single instrument per track receives them on one channel, as live input does today.+- Built-in instruments are not taught new controllers by this feature; each keeps reacting to what it understands today (pedal, wheel, pressure, CC74). Plug-ins receive everything.+- The pitch wheel's range is the instrument's own setting; the clip stores the wheel position, not semitones.+- Existing MIDI Learn bindings, MIDI FX that output CCs (`nota_midi_effect_set_cc_*`) and gamepad mapping keep working unchanged.+- MCP tools for reading/writing controller data and CC automation follow the existing MCP patterns; the exact tool set is decided in the plan.+- The three stories land as separate pull requests (Story 1, then 2, then 3) to keep each change small, per the constitution.++## 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.md` row 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.h` only (AR-7); no JUCE outside `pluginhost/`+- [ ] 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` (Studio design language)diff --git a/specs/020-midi-cc-record-automate/tasks.md b/specs/020-midi-cc-record-automate/tasks.mdnew file mode 100644index 00000000..ae76c8bc--- /dev/null+++ b/specs/020-midi-cc-record-automate/tasks.md@@ -0,0 +1,418 @@+---++description: "Task list for recording and automating MIDI CC (#69)"+---++# Tasks: Record and automate MIDI CC++**Input**: Design documents from `/specs/020-midi-cc-record-automate/`++**Prerequisites**: [plan.md](plan.md), [spec.md](spec.md), [research.md](research.md), [data-model.md](data-model.md), [contracts/](contracts/), [quickstart.md](quickstart.md)++**Tests**: Included. The constitution (IV) and FR-018 require smoke coverage of recording, playback, chase, the end-of-clip release and the new C ABI. The UI is checked with the headless capture recipe in quickstart.md.++**Organization**: Tasks are grouped by user story. Each story is one pull request (spec Clarifications): US1 → PR 1, US2 → PR 2, US3 → PR 3.++## Format: `[ID] [P?] [Story] Description`++- **[P]**: Can run in parallel (different files, no dependencies)+- **[Story]**: Which user story this task belongs to (US1–US3)++## Path Conventions++- Engine: `src/native/nota.engine/src/`, C ABI `src/native/nota.engine/include/nota/nota_engine.h`, plug-in host `src/native/nota.engine/pluginhost/PluginHost.cpp`+- Managed: `src/managed/Nota.Application/`, `src/managed/Nota.Infrastructure/`, `src/managed/Nota.App/`, `src/managed/Nota.Mcp/`+- Smoke tests: `tests/Nota.SmokeTest/`++---++## Phase 1: Setup++**Purpose**: Test scaffolding the stories add to.++- [X] T001 Create `tests/Nota.SmokeTest/MidiControllerTests.cs`:+ - Start it with the two-line AGPL SPDX header.+ - Add a `static class MidiControllerTests` exposing `IEnumerable<(bool, string)> Run()` and a `Render(NotaEngine, int blocks)` helper modelled on `MpeTests.Render` (`tests/Nota.SmokeTest/MpeTests.cs:26`).+ - Register it in `tests/Nota.SmokeTest/Program.cs` next to `MpeTests.Run()`. There are two registration sites, around L379 and L14647; add it at both, matching how `LiveRecordTests` is registered.++---++## Phase 2: Foundational (Blocking Prerequisites)++**Purpose**: The controller id space, the curve type, the instrument entry point and the wire through the engine. Every story builds on these. They ship in PR 1.++**⚠️ CRITICAL**: No user-story work can begin until this phase is complete.++- [X] T002 [P] Create `src/native/nota.engine/src/MidiController.h` (SPDX header, `namespace nota`) with:+ - **Constants**: `kCtlPitchWheel = 128`, `kCtlChannelPressure = 129`, `kCtlCount = 130`, `kCtlDimBase = 16`.+ - **Helpers**:+ - `ctlIsReserved(ctl)`: true for CC 6, 38, 96–101, 120–127 and any ctl > 129.+ - `ctlIsSwitch(ctl)`: CC 64–69.+ - `ctlRest(ctl)`: 0 for all.+ - `ctlRange(ctl)`: wheel −1..+1, others 0..1.+ - **`struct ControllerCurve { int32_t ctl; std::vector<AutomationPoint> points; float valueAt(double beat) const; }`**:+ - Points are sorted by beat, clip-local, may be < 0, at most one per beat.+ - Step ctls take the last point ≤ beat.+ - Linear ctls reuse `AutomationLane::shape`.+ - Held before the first and after the last point.+ - **`thinCtlCurve(points, tol)`**: RDP over `AutomationPoint`, mirroring `thinExprCurve` in `MidiClip.h`.+ - **`dedupeSwitch(points)`**: drops points equal to the previous value.+- [X] T003 Extend `MidiClip` in `src/native/nota.engine/src/MidiClip.h` with `std::vector<std::shared_ptr<const ControllerCurve>> controllers;`. There is at most one per ctl, sorted by ctl, and empty means none. Add the helpers `const ControllerCurve* controller(int32_t ctl) const` and `void setController(int32_t ctl, std::vector<AutomationPoint> pts)` (empty removes). Include `MidiController.h` (depends on T002).+- [X] T004 [P] Add `virtual void controller(int32_t ctl, float value)` to `src/native/nota.engine/src/Instrument.h`. The default maps 128 → `noteExpression(-1, ExprBend, v)`, 129 → `(-1, ExprPressure, v)`, 74 → `(-1, ExprSlide, v)` and 64 → `(-1, ExprSustain, v)`, and ignores everything else (contracts/instrument.md).+- [X] T005 [P] Override `controller` in `src/native/nota.engine/src/RackInstrument.h` to forward to every chain's instrument, the same way its `noteExpression` override does (L60). This also covers `DrumRack.h`.+- [X] T006 [P] Make sustain continuous on the wire. In `src/native/nota.engine/src/MpeInput.h` `controlChange` case 64, emit `v / 127.0f` instead of `0|1`. Check that `Keys.h` L191, `PhysicalSynth.h` and every other `ExprSustain` reader threshold at `>= 0.5f`.+- [X] T007 Route controllers through the live path in `src/native/nota.engine/src/MpeInput.h`.+ - Add `virtual void mpeController(int32_t ctl, float value)` to `MpeInput::Sink`.+ - On non-member channels: emit the wheel (0xE0) and channel pressure (0xD0) as `mpeController(128|129, …)`, and CC74 as `mpeController(74, …)`, instead of `mpeExpression(-1, …)`.+ - CC64 on any channel goes to `mpeController(64, v/127)`.+ - In `controlChange`'s `default:` branch, emit every other non-reserved CC as `mpeController(cc, v/127)`. On member channels CC74 stays per-note.+ - Update the selftest expectations in `src/native/nota.engine/src/nota_engine_audio.cpp` (~L149–181) so `nota_mpe_selftest` still passes.+ - Depends on T002 and T006.+- [X] T008 In `src/native/nota.engine/src/Engine.h` and `Engine_Recording.cpp`:+ - Implement `MpeSink::mpeController` and new `Engine::controller(ctl, v)` / `Engine::trackController(trackId, ctl, v)`. They push `MidiEvent{on=false, pitch=-1, velocity=v, trackId, expr=kCtlDimBase+ctl}` through the same producer locks as `noteExpression`.+ - Rewrite `Engine::noteExpression` / `trackNoteExpression` with `pitch == -1 && dim <= 3` to the matching controller (128/129/74/64).+ - Store each live controller's latest value and a touch counter in `std::atomic<float> liveCtl_[kCtlCount]` and `std::atomic<uint32_t> liveCtlTouch_[kCtlCount]`. These are used by take seeding (T018) and automation writing (T046).+- [X] T009 Dispatch controller dims in `src/native/nota.engine/src/Engine_Render.cpp`:+ - In `playEvents` (L124), send `xev[x].dim >= kCtlDimBase` to `inst.controller(dim - kCtlDimBase, value)` and keep `noteExpression` for the rest.+ - In `applyLiveExpression` (L723) and the slot monitor lambda in `renderSessionSlotRaw` (~L949), do the same split.+ - In `drainLiveMidi`'s coalescing (L540), key controllers by (track, expr), which already works since `pitch` is −1.+- [X] T010 [P] Override `controller` in the plug-in host, `src/native/nota.engine/pluginhost/PluginHost.cpp`, next to `noteExpression` (L711):+ - 0..127 → `juce::MidiMessage::controllerEvent(1, ctl, u7(v))`, with CC64 exact (no threshold).+ - 128 → `pitchWheel(1, jlimit(0,16383, lround((v+1)*8191.5)))`.+ - 129 → `channelPressureChange(1, u7(v))`.+ - Remove the pitch −1 branches from `noteExpression` that the default `controller` now covers, so nothing is sent twice.+- [X] T011 [P] Map CC1 to the *Mod Wheel* parameter in built-ins that have one. Override `controller` in `src/native/nota.engine/src/BassSynth.h`, `OperatorSynth.h` and `Consort.h`, and in any other synth whose parameter ids include `"modwheel"` (find them with `grep -n '"modwheel"' src/native/nota.engine/src/*.h`). For `ctl == 1`, set `ModWheel` to `v` with the same write automation uses, then call `Instrument::controller(ctl, v)`.+- [X] T012 Add the C ABI declarations from [contracts/c-abi.md](contracts/c-abi.md) to `src/native/nota.engine/include/nota/nota_engine.h`:+ - `NOTA_CTL_PITCH_WHEEL` / `NOTA_CTL_CHANNEL_PRESSURE` / `NOTA_CTL_COUNT`;+ - `nota_engine_controller` / `nota_track_controller`;+ - `nota_midi_clip_ctl_list/get/set`, `nota_session_ctl_list/get/set`;+ - `nota_engine_midi_ctl_selftest`.++ Implement the live pair in `src/native/nota.engine/src/nota_engine_core.cpp` next to `nota_engine_note_expression`. Add the new symbols to `src/native/nota.engine/nota_exports.map` and `nota_exports.txt`.+- [X] T013 [P] Add the managed contracts:+ - `src/managed/Nota.Application/Engine/EngineContracts.cs`: a `public static class MidiController` with `PitchWheel = 128`, `ChannelPressure = 129`, `Count = 130`. It provides `Name(ctl)` (standard CC names: "Mod wheel", "Breath", "Volume", "Pan", "Expression", "Sustain", …, "CC 3" when unnamed), `ShortName(ctl)`, `IsSwitch(ctl)`, `IsReserved(ctl)` and `Range(ctl)`. The values must match data-model.md exactly.+ - `IAudioEngine.cs`: `SendController(int ctl, float value)`, `SendTrackController(int trackId, int ctl, float value)`, `GetMidiClipControllers(track, clip) → int[]`, `GetMidiClipController(track, clip, ctl) → NotaAutomationPoint[]`, `SetMidiClipController(track, clip, ctl, NotaAutomationPoint[])`, plus `GetSessionControllers` / `GetSessionController` / `SetSessionController`.+- [X] T014 Add P/Invokes in `src/managed/Nota.Infrastructure/Interop/NativeMethods.Tracks.cs` and implementations in `NotaEngine.Tracks.cs` for every T012 function, following the `nota_midi_clip_env_get/set` pattern: count-then-fill (`out = null`). Also implement them in any test or fake `IAudioEngine` the build requires (find with `grep -rln ": IAudioEngine" src tests`). Depends on T012 and T013.++**Checkpoint**: Controllers flow live from MIDI input to built-ins and plug-ins (FR-004), and the ABI compiles. Nothing is recorded yet.++---++## Phase 3: User Story 1 — Record the sustain pedal, wheels and CCs with the notes (Priority: P1) 🎯 MVP · PR 1++**Goal**: Takes store every controller next to the notes, play them back with chase and end-of-clip release, carry them through clip edits, and save and load them (FR-001–FR-009, FR-018–FR-021).++**Independent Test**: Record a phrase with the pedal, mod wheel and a bend. Play it from the start and from the middle; the instrument follows and no note hangs after stop (quickstart PR 1, steps 1–7).++### Tests for User Story 1++> Write first. They fail until the implementation lands.++- [X] T015 [P] [US1] In `tests/Nota.SmokeTest/MidiControllerTests.cs`, add `RoundTrip()`:+ - Set CC64 (step), CC1 and wheel curves on a MIDI clip through `SetMidiClipController`. Read back with `GetMidiClipControllers` / `GetMidiClipController`.+ - Removal with 0 points works.+ - Reserved CCs are refused: 6, 38, 96–101, 120–127, and ctl > 129.+ - Undo restores a set.+ - Check 2 in contracts/c-abi.md.+- [X] T016 [P] [US1] In `MidiControllerTests.cs`, add `Recording()`, modelled on `MpeTests.Recording` (`MpeTests.cs:184`):+ - Arm, record, then `SendTrackController` CC64 1→0, a wheel ramp −1→1 over 2 beats, and CC1 steps. Stop.+ - The take holds those curves at the expected beats within one block. The wheel ramp is thinned to ≤ 16 points. CC64 has exactly two points.+ - Recording starts with the pedal already down: a point at the take start with value 1.+ - Checks 3 and 11: poly aftertouch 0xA0 through `nota_engine_note_expression(pitch, 1, v)` lands in the note's pressure curve.+- [X] T017 [P] [US1] In `MidiControllerTests.cs`, add `Playback()`, `Chase()`, `EndRelease()`, `OverdubFold()`, `PedalOnlyReplace()` and `Persistence()` (checks 4–8 and 10):+ - **Probe**: read what reached the instrument with `nota_track_delivered_controller` (added to the ABI for this; no test-only instrument kind needed).+ - **Persistence**: save and load the project through `ProjectService`. A v21 file loads with no controllers.++### Implementation for User Story 1++- [X] T018 [US1] Capture on the audio thread, in `src/native/nota.engine/src/Engine.h` and `Engine_Render.cpp`:+ - Add `struct RecordedCtl { int32_t ctl; double beat; float value; int32_t pass; }` with `using RecordedCtlQueue = SpscRingBuffer<RecordedCtl, 1u << 14>;` and an `Engine::recordedCtl_` member.+ - At the end of `drainLiveMidi`, when `rec && timed`, push every coalesced `liveExpr_` entry with `expr >= kCtlDimBase` whose `trackId < 0 || trackId == recTrack`, at `nowBeat` (slot-local for Session takes) with `recordPass_`.+ - On `takeStarted`, seed every ctl whose `liveCtl_` value is off rest (`!= ctlRest`, wheel `!= 0`) as a point at `nowBeat`.+ - In `renderInstrumentRaw`, when `captureRouted`, push the source's controller `ExprEv`s (dim ≥ `kCtlDimBase`) at `(blockStart + off) / spb + countInClockOffset()`.+ - Allocate nothing, and drop on a full queue the way `recorded_` does (AR-6).+- [X] T019 [US1] Fold the queue into the take in `Engine::poll()` in `src/native/nota.engine/src/Engine_Render.cpp`, after `collectRecordedExpr()`. Keep message-thread per-take state, `std::array<CtlFold, kCtlCount> ctlFold_` (pending raw points, last committed point, replace range start, range pass), and reset it in `setRecording` (`Engine_Recording.cpp:245`).+ - **Conversion**: each poll converts absolute beats to clip-local beats.+ - **Thinning**:+ - Switch ctls use `dedupeSwitch`.+ - Linear ctls use `thinCtlCurve`, anchored on the last committed point, with tolerances CC 0.004, wheel 0.002, pressure 0.004 (research R5).+ - **Replace range** (FR-021): remove the clip curve's existing points in `[rangeStart, latest]`, insert the new points, and publish a new `shared_ptr<const ControllerCurve>`.+ - **Pickups**: when the pickup left-edge move shifts `clip.notes` (L306), shift every controller point by the same delta.+ - **Session takes**: points use `fmod` into `[0, L)`, as notes do.+ - Republish with `republishWithTrackRaw` in the same call that publishes the notes (no extra undo step). A poll that has only controller points must still republish: relax the `batch.empty()` early return.+- [X] T020 [US1] Close replace ranges in `src/native/nota.engine/src/Engine_Render.cpp` and `Engine_Recording.cpp`:+ - **Loop wrap**: `onLoopWrap` (L1128) pushes a marker (`RecordedCtl{ctl=-1, beat=loopEnd, pass}`). `poll` closes every open range at the loop end.+ - **Record stop**: in `setRecording(false)`, close open ranges at the stop beat with a junction point carrying the old curve's value there.+ - **Replace mode**: when `replacePending` removes earlier-pass notes, also remove this take's earlier-pass controller points. Track them per pass in `ctlFold_`.+ - Controllers never call `triggerPassReplace`, so a pedal-only pass keeps the notes (clarification 2).+- [X] T021 [US1] Emit clip controllers on playback in `gatherInstrumentNotes` (`src/native/nota.engine/src/Engine_Render.cpp:655`). For each active clip with `controllers`, push `ExprEv{off, -1, kCtlDimBase+ctl, value}` into `xev`:+ - at each point inside `[blockStart, blockStart+frames)`;+ - every 64 samples while a linear curve moves (mirror `noteExprEvents`, L154);+ - at offset 0 when `chaseNotes_`, or when the block contains the clip start, with `valueAt` there (FR-005).+ - Skip a ctl that has a track automation lane with points and `target == MidiController`. Use a precomputed per-track bitset; for PR 1 it is always empty and is filled in T045.+ - Respect `kMaxBlockExpr`.+- [X] T022 [US1] Release at clip end and on stop, in `src/native/nota.engine/src/Engine_Render.cpp` and `Track.h`:+ - Add audio-side `float lastCtl_[kCtlCount]` (NaN-initialised) on `Track`, written from `playEvents` for controller dims.+ - In `gatherInstrumentNotes`, when a clip's end falls in the block and its CC64 or wheel value at the end is off rest, emit `ExprEv` CC64 = 0 and wheel = 0 at the end offset. Sort the reset ahead of a following clip's chase at the same offset by using a stable sort with resets inserted first.+ - On transport stop, find where `allNotesOff` is sent on stop (`grep -n "allNotesOff" src/native/nota.engine/src/Engine_Render.cpp`). Send `controller(64, 0)` and `controller(128, 0)` to every instrument whose `lastCtl_` for those is off rest (FR-006).+- [X] T023 [US1] Play slot controllers in `renderSessionSlotRaw` (`src/native/nota.engine/src/Engine_Render.cpp:888`):+ - For iterations `i0..i0+1`, emit the slot clip's controllers like T021.+ - At each loop start `it * L` inside the block, emit a chase of `valueAt(0)`.+ - On a one-shot slot's end, release like T022.+- [X] T024 [US1] Carry controllers through clip edits in `src/native/nota.engine/src/Engine_Tracks.cpp` (data-model.md):+ - **`splitClip`**: the left clip keeps points `< b` plus a point at `b` with `valueAt(b)`. The right clip gets a point at 0 with `valueAt(b)`, then the rest shifted by −b.+ - **`trimClip`** and left-edge moves: shift points with the clip start, as notes are shifted.+ - **`splitClipsAtRange`**, **`consolidateRange`** and the join path near L1804 (`stitchEnvelopes`): stitch curves per ctl, with a rest-value point where a source clip ended inside the result.+ - **`copyClip` / `pasteClip` / block paste / cross-track move**: the vector copies with the clip, so verify it, and fix any place that rebuilds a `MidiClip` field by field.+ - **Quantize**: unchanged.+- [X] T025 [US1] Carry controllers between slot and arrangement in `src/native/nota.engine/src/Engine_Session.cpp`: `nota_session_slot_to_arrangement`, `pasteClipBlockToSession` and any arrangement → slot path. Points are shifted into or out of the slot's `[0, L)`, and points outside are dropped.+- [X] T026 [US1] Implement the clip and slot controller ABI in `src/native/nota.engine/src/nota_engine_track.cpp` and `nota_engine_session.cpp`, through new `Engine` methods in `Engine_Automation.cpp` next to `getMidiClipEnvelope` / `setMidiClipEnvelope` (L741):+ - `list` returns sorted ctls.+ - `get` uses count-then-fill.+ - `set` sorts the points, keeps the last point per beat, refuses reserved ctls (`NOTA_ERR_*` as the env setters do), and takes one undo checkpoint.+- [X] T027 [US1] Implement `nota_engine_midi_ctl_selftest` in `src/native/nota.engine/src/Engine_Automation.cpp` (device-free, numbered checks, 0 = pass). It covers:+ - `valueAt` step and linear;+ - split and trim carry;+ - chase value;+ - end release emission;+ - precedence skip (with a lane injected directly);+ - the overdub touched-range fold, run on synthetic `RecordedCtl`s.++ Call it from `MidiControllerTests.Run()` (check 1).+- [X] T028 [P] [US1] Persistence v22 in `src/managed/Nota.Infrastructure/Persistence/`:+ - **Model**: add `ControllerCurveDto { int Ctl; AutomationPointDto[] Points }` to `ProjectModel.cs`, and add `ControllerCurveDto[]? Controllers` to `MidiClipDto` (L341) and `SessionSlotDto` (L378).+ - **Save**: in `ProjectService.cs`, write the controllers next to the clip envelopes (L194–204) and the slot notes.+ - **Load**: restore them next to L638–641 and in the slot load. Drop reserved or unknown ctls with a `warnings.Add`.+ - **Version**: bump `CurrentFormatVersion` to 22 (L34) and add a no-op step in `ProjectMigrations.cs` if the file requires one per version.+ - Older Nota builds keep unknown fields through `[JsonExtensionData]`, so nothing else is needed.+- [X] T029 [US1] Verify that note edits keep controllers: `src/managed/Nota.App/ClipEditorView.cs` note edits (set-notes calls) must not rebuild the `MidiClip` without its `controllers`. Check the engine side of `nota_set_notes` in `src/native/nota.engine/src/nota_engine_track.cpp` and fix it if needed. Controllers are not drawn in PR 1 (FR-022 and US2).+- [X] T030 [US1] Add MCP tools in `src/managed/Nota.Mcp/Tools/MidiTools.cs`, following the existing tool style and argument validation:+ - `get_clip_controllers(track, clip)`: the list plus the points per ctl, with names from `MidiController.Name`.+ - `set_clip_controller(track, clip, ctl, points)`: an empty list removes the curve.+ - `ctl` accepts a number, "pitch_wheel", "channel_pressure", "sustain" or "mod_wheel".++ If the MCP golden tests list tools (`tests/Nota.SmokeTest/AiGoldenTests.cs`, `McpTestSupport.cs`), update them.+- [X] T031 [US1] Run `MidiControllerTests` through `scripts/build.sh` and fix until checks 1–8, 10 and 11 pass.++**Checkpoint**: PR 1 is complete. Recording and playback work end to end and are saved with the project.++---++## Phase 4: User Story 2 — See and edit controller lanes in the piano roll (Priority: P2) · PR 2++**Goal**: A fifth lane tab with a controller picker. The sustain pedal is drawn as blocks, every other controller as an editable curve, and each gesture is one undo step (FR-010–FR-013, contracts/ui-lanes.md).++**Independent Test**: In clips with and without recorded data, switch to Sustain, Mod wheel, Pitch wheel, Channel pressure and CC 74. Draw, move and delete, undo each step, and confirm playback follows (quickstart PR 2).++- [ ] T032 [US2] Extend `LaneMode` in `src/managed/Nota.App/PianoRollView.Expression.cs` (L33) with `Controller`, and add a `_laneCtl` field.+ - **Default**: the first ctl with data in the clip, else 64. Remember it per editor session, like `_laneMode`.+ - **Height**: `SetLaneMode(Controller)` swaps in the new lane control at `ExprH`.+ - **Tab**: `LaneTabs` (L134) gains a fifth tab labelled with `MidiController.ShortName(_laneCtl)`, keeping the existing tab styling.+- [ ] T033 [US2] Add the controller picker to the fifth tab in `src/managed/Nota.App/PianoRollView.Expression.cs`. A click on the active tab or its chevron opens a menu:+ - first, the ctls with data in this clip, each marked with the automation picker's dot (reuse `AutoDot()` from `ArrangementView.Automation.cs:612`, or lift it into a shared helper in `ClipEditorKit.cs`);+ - then Sustain, Mod wheel, Pitch wheel, Channel pressure, Expression (CC11) and Breath (CC2);+ - then **Other CC ▸** with 0–127 in groups of 16, labelled "CC 7 — Volume", skipping reserved CCs.++ Labels are in sentence case.+- [ ] T034 [US2] Create `src/managed/Nota.App/PianoRollView.Controllers.cs` (SPDX header, `partial class PianoRollView`) with a `ControllerLane` control. It reads the curve through a host delegate `Func<int, NotaAutomationPoint[]>? GetController` and writes through `Action<int, NotaAutomationPoint[]>? SetController`, mirroring `CreateExpression`.+ - **Time mapping**: the same as the notes over the whole clip. A pickup before the clip start is drawn faintly.+ - **Ink**: neutral (`NotaPalette.VizInk`, `CurvePen`). Only the hovered point or block, and the selection, use the accent.+- [ ] T035 [US2] Switch controllers (CC64–69) in `PianoRollView.Controllers.cs`:+ - **Drawing**: blocks where the value is ≥ 0.5. Fill height shows partial values (clarification 3).+ - **Drag on empty lane**: draws a block that snaps to the grid; ⌘ or Ctrl turns snap off.+ - **Drag an edge**: resizes the block.+ - **Drag the body**: moves the block.+ - **Delete**: double-click, or Delete with the block selected.+ - **Right-click**: *Clear <name>*.+ - A block is serialised as two step points: on at its start, off at its end.+- [ ] T036 [US2] Continuous controllers in `PianoRollView.Controllers.cs`:+ - **Drawing**: a curve with points. The range lines are 0–127 with a midline label. The pitch wheel draws a centre line and ±full travel, and points within 2% of centre snap to 0.+ - **Freehand drag**: replaces the points under the stretch; ⌥ draws a straight line.+ - **Points**: drag a point to move it between its neighbours; double-click adds or deletes a point.+ - **Right-click**: *Clear <name>*.+ - **Hover readout**: the value in the controller's units ("64", "+0.42", "on / off").++ Reuse the point-drag and freehand helpers from `PianoRollView.Expression.cs`. If they are private to the MPE lane, lift them into a shared helper.+- [ ] T037 [US2] Wire the host in `src/managed/Nota.App/ClipEditorView.cs`:+ - Set `GetController` / `SetController` to `IAudioEngine.GetMidiClipController` / `SetMidiClipController` for arrangement clips, and the `Session*` variants for slots.+ - `SetController` is called once on gesture release (one undo step, FR-013).+ - Refresh the lane after undo and redo and when the take republishes during recording, the same way notes refresh.+- [ ] T038 [US2] Add a precedence note to the controller lane. When the track has a target-5 automation lane with points for `_laneCtl`, show the one-line note "Track automation overrides this lane" in `PianoRollView.Controllers.cs`. The data comes from `IAudioEngine.AutomationLaneInfo`. It is inert until US3 adds the target; no US3 dependency for compiling, because the enum value is added in T042.+- [ ] T039 [US2] Visual check following quickstart PR 2. Run the headless Avalonia render, or the env-guarded in-app capture with `NOTA_DATA_DIR`, for Sustain blocks and a CC curve in Studio Dark and Studio Light. Then run the `DesignTokenCheck*` tests in the smoke suite (labels, numbers, radius allow-lists). Fix violations, or add allow-list rows only where the design guide permits.++**Checkpoint**: PR 2 is complete. Controllers are visible and editable.++---++## Phase 5: User Story 3 — Automate a CC on an instrument track (Priority: P3) · PR 3++**Goal**: Track automation lanes can target a MIDI controller and take precedence over the clip's data. Hardware moves record into them with Record engaged (FR-014–FR-017).++**Independent Test**: Add a CC74 lane on a plug-in instrument track and draw it across two clips; the plug-in follows. Add a Mod wheel lane and record it with the hardware wheel. Where the lane has points, it overrides clip data (quickstart PR 3).++### Tests for User Story 3++- [ ] T040 [P] [US3] In `MidiControllerTests.cs`, add `Automation()` (check 9 plus lane playback):+ - A target-5 lane on CC1 with points 0→1 drives the probe's `controller(1, …)` across two clips and is sent only on change.+ - The clip's own CC1 is ignored where the lane has points.+ - Persistence round-trips the lane.+ - Adding a target-5 lane on an audio track, or for a reserved CC, fails.+- [ ] T041 [P] [US3] In `MidiControllerTests.cs`, add `AutomationRecord()`:+ - Turn on `nota_engine_set_automation_record(1)`, arm the track with a CC1 lane, play, and send `SendTrackController(1, …)` values. `poll` writes them into the lane, latched until stop.+ - While the lane exists, the take captures no CC1 into the clip.++### Implementation for User Story 3++- [ ] T042 [P] [US3] Add the target:+ - `MidiController = 5` to `AutomationTarget` in `src/native/nota.engine/src/Automation.h` (L19) and in `src/managed/Nota.Application/Engine/EngineContracts.cs` (L252).+ - Document target 5 in the M9 comment block of `nota_engine.h` (L318).+- [ ] T043 [US3] Accept target 5 in `Engine::addAutomationLane` (`src/native/nota.engine/src/Engine_Automation.cpp:490`): `deviceIndex = -1`, `paramIndex = ctl`. Refuse it on non-instrument tracks and for reserved ctls, and reuse an existing lane for the same ctl. Make `automationLaneInfo`, `remapAutomationAfterDeviceChange` (unaffected, ctl lanes have no device) and `currentTargetValue` handle it. `currentTargetValue` returns `liveCtl_[ctl]`, or the track's `lastCtl_` when the controller is untouched.+- [ ] T044 [US3] Play target-5 lanes in `applyAutomation` (`src/native/nota.engine/src/Engine_Automation.cpp:25`): `v = lane.valueAt(beat)`. If `t.instrument` exists and `v` differs from `t.lastCtl_[ctl]`, call `t.instrument->controller(ctl, v)` and update `lastCtl_`. Clamp to `ctlRange`.+- [ ] T045 [US3] Precedence. When a track snapshot is built or published (`cloneTrack` or the automation setters), compute a per-track `std::bitset<kCtlCount> ctlAutomated` of ctls that have a target-5 lane with points. Store it on `Track` in `src/native/nota.engine/src/Track.h`. `gatherInstrumentNotes` (T021) and `renderSessionSlotRaw` (T023) skip clip emission for those ctls.+- [ ] T046 [US3] Record target-5 lanes from hardware, in `Engine::poll()` (`src/native/nota.engine/src/Engine_Render.cpp:209`) in the automation block. When `rec && playing`:+ - for each ctl whose `liveCtlTouch_` changed since the last poll, and where the armed record track has a target-5 lane for it, call `beginAutomationWrite(track, 5, -1, ctl, nullptr, /*latched*/true)` once;+ - `sampleAutomationWritesAt` then reads `currentTargetValue`;+ - stop ends the write through the existing `finishAllWrites`.++ Also make T018 capture skip ctls in the record track's `ctlAutomated` (automation wins).+- [ ] T047 [US3] Add the target picker in `src/managed/Nota.App/ArrangementView.Automation.cs`:+ - **Submenu**: in the picker (L355), add **MIDI controllers ▸** after the instrument's parameters, on instrument tracks only. It lists the T033 entries without clip dots and with the automated-target dot. Leaf key `"C:{ctl}"`; apply sets `t.AutoTarget = MidiController` and `t.AutoParamIndex = ctl`.+ - **Labels**: extend the label switch (L27) with `MidiController.ShortName(ctl)`.+ - **Range**: extend the range switch (L40): the wheel is (−1, 1), others (0, 1). Display 0–127 for CCs.+ - **Value**: extend the current-value switch (L56).+ - **Matching**: extend the target-matching code (L83, L114, L126, L147).+- [ ] T048 [US3] Persist target-5 lanes in `src/managed/Nota.Infrastructure/Persistence/ProjectService.cs` (L258–271 save, L685–707 load). They go through the existing `AutomationLaneDto` with `Target = 5`, `DeviceIndex = -1` and `ParamIndex = ctl`. Verify the generic `AddAutomationLane` path covers them; add a warning on refusal.+- [ ] T049 [US3] Add MCP support in `src/managed/Nota.Mcp/Tools/AutomationTools.cs`: accept `target: "midi_cc"` with `ctl` (number or name, as T030) to create, read and write lanes, and report target-5 lanes with their controller name. Update the golden tool lists if they exist.+- [ ] T050 [US3] Visual check of the picker submenu and a drawn CC74 lane (quickstart PR 3), with the same capture recipe and `DesignTokenCheck*` run as T039.++**Checkpoint**: PR 3 is complete. All three stories work.++---++## Phase 6: Polish & Cross-Cutting Concerns++**Purpose**: Release-quality wrap-up. Repeat the parts relevant to each PR before it is opened.++- [ ] T051 [P] FEATURES.md via the `nota-features` skill. **PR 1**: replace "The pitch wheel, channel pressure and sustain pedal aren't recorded" (FEATURES.md ~L303) with the recording capability, including all CCs live to plug-ins, CC1 → Mod Wheel on built-ins and poly aftertouch as per-note pressure. **PR 2**: the controller lanes. **PR 3**: the MIDI controller automation target (Automation section, ~L405).+ - PR 1 done 2026-10-16: new "MIDI controllers in clips" bullet; the "aren't recorded" sentence removed; MCP section updated.+- [ ] T052 [P] User docs, EN and RU, via the `nota-docs` skill: the recording page (PR 1), the piano roll lanes page (PR 2) and the automation page (PR 3), with screenshots from T039 and T050.+ - PR 1 done 2026-10-16: `control/midi` (new "Sustain pedal, mod wheel and other controllers" section) and `editing/recording` ("Pedal, wheels and controllers", loop pass rule), EN + RU; `coverage.yml` updated; `npm run build` / `npm run check` clean. No screenshots: no UI change in PR 1. Not committed in ../nota-docs.+- [ ] T053 [P] `CHANGELOG.md` `[Unreleased]`, one entry per PR, in the repo's existing style: Added for recording and playback of controllers, then controller lanes, then CC automation. Changed for the sustain pedal now reaching plug-ins with its exact value, and every CC passed to plug-ins live.+ - PR 1 done 2026-10-16: Added "Record the sustain pedal, the wheels and any CC"; Changed "Hosted plug-ins get every MIDI controller".+- [ ] T054 Run `nota-shortcuts` to confirm no binding changed; mark N/A if none did. The lane gestures reuse the existing ones.+ - PR 1: N/A, no binding changed.+- [ ] T055 Performance pass: record 2 minutes of continuous wheel movement and check SC-005 (project growth ≤ 100 KB, no new dropouts in `TimingBudget`). Check that the per-poll republish stays cheap, since curves are shared.+ - PR 1 done 2026-10-16: `MidiControllerTests.LongTake` (2 min of wheel + mod wheel over a played part, ~30 Hz polls). First run: 7502 points / +1.1 MB, because each poll thinned its own short run. Fixed: a moving curve keeps its last thinned segment back between polls (committed at range end/stop, capped at 512 points); the controller DTO became parallel arrays rounded to 1e-6 beat / 1e-4 value. Now 1690 points / +84.5 KB; render mean 2.6 → 2.9 µs per 256-frame block, worst 34 µs of 5333 µs.++### Nota closing tasks *(PR gates, for every PR)*++- [ ] T056 Run `scripts/build.sh` until native, managed and the smoke test are green.+ - PR 1: green 2026-10-16 (`scripts/build.sh` exit 0, smoke passed, no new compiler warnings).+- [ ] T057 Check that every new source file carries the AGPL-3.0-only SPDX two-line header: `MidiController.h`, `PianoRollView.Controllers.cs`, `MidiControllerTests.cs` and any probe instrument.+ - PR 1: checked (`MidiController.h`, `MidiControllerTests.cs`).+- [ ] T058 New dependency: none → N/A.+ - PR 1: N/A.+- [ ] T059 User-visible change → `CHANGELOG.md` entry (T053).+- [ ] T060 FEATURES.md and docs (T051, T052); shortcuts (T054).+- [ ] T061 Engine behaviour change → smoke coverage (T015–T017, T027, T040, T041).++---++## Dependencies & Execution Order++### Phase Dependencies++- **Setup (T001)**: none.+- **Foundational (T002–T014)**: depends on Setup and blocks every story.+ - T003 needs T002.+ - T007 needs T002 and T006.+ - T008 needs T007.+ - T009 needs T004 and T008.+ - T012 → T014; T013 → T014.+- **US1 (T015–T031)**: after Foundational.+ - T018 → T019 → T020.+ - T021 → T022 → T023.+ - T026 needs T003 and T012.+ - T027 needs T019 and T021–T024.+ - T031 needs all of US1.+- **US2 (T032–T039)**: needs US1's ABI (T026) and interop (T014). The rest of US1 is not needed.+- **US3 (T040–T050)**: needs Foundational and T021 (the precedence hook). It is independent of US2. T038 lights up once T042 lands.+- **Polish (T051–T061)**: per PR, after that story.++### Within Each User Story++- Tests are written first and fail before the implementation.+- Engine first, then ABI, then interop and persistence, then UI and MCP.++### Parallel Opportunities++- **Foundational**: T002, T004, T005, T006, T010, T011 and T013 touch different files.+- **US1**: T015, T016 and T017 (one test file, separate methods; parallel only if they are merged carefully, otherwise sequential). T028 and T030 run alongside the engine work (T018–T027) once T014 is done.+- **US3**: T040 and T041 alongside T042.+- **Polish**: T051, T052 and T053.++---++## Parallel Example: Foundational++```bash+Task: "Create MidiController.h (T002)"+Task: "Instrument::controller default (T004)"+Task: "RackInstrument forwards controller (T005)"+Task: "Plug-in host controller override (T010)"+Task: "CC1 → Mod Wheel in built-ins (T011)"+Task: "Managed MidiController + IAudioEngine (T013)"+```++## Parallel Example: User Story 1++```bash+Task: "Persistence v22 DTOs and save/load (T028)"+Task: "MCP get/set_clip_controller (T030)"+# while the engine capture/fold/playback chain T018 → T023 runs sequentially+```++---++## Implementation Strategy++### MVP First (User Story 1 = PR 1)++1. T001, then Foundational T002–T014.+2. US1, T015–T031.+3. **Stop and validate**: run quickstart PR 1 and `scripts/build.sh`. Then the closing tasks and PR 1.++### Incremental Delivery++1. PR 1 (US1): recording and playback; data saved; MCP access.+2. PR 2 (US2): piano-roll lanes.+3. PR 3 (US3): CC automation target, recording and precedence.++Each PR leaves `develop` releasable.++---++## Notes++- **Audio-thread rule** (AR-6): T018, T021–T023 and T044 must stay allocation-free and lock-free. Use fixed arrays, SPSC queues and snapshot reads only.+- **Commits**: the user makes their own commits. Leave changes for review and do not commit or push.+- **Re-verify line numbers**: the line numbers above are from `develop` @ d724fb5.++## Phase 7: Convergence++Assessed 2026-10-16 for **PR 1 scope only** (Setup, Foundational, US1; FR-001–FR-009,+FR-018–FR-022 as they apply to recording and playback). US2 and US3 are intentionally unbuilt+and not assessed.++- [X] T062 Flush the held-back controller tail when a take ends without `setRecording(false)`. In `Engine::finalizeSessionRecord` (`src/native/nota.engine/src/Engine_Session.cpp`), before `recordSessionScene_` is cleared, drain `recordedCtl_` and fold into the slot clip with every open range committed in full: set `ctlStopPending_` and call `foldRecordedCtl(slot.midi, L)` on a cloned track, then `republishWithTrackRaw`. In `Engine::setTrackArmed` (`src/native/nota.engine/src/Engine_Recording.cpp`), disarming the record track does the same into the arrangement take before `recordClipIndex_` is reset. Today the last segment of a moving curve (up to one poll's worth) is lost on both paths, per FR-002 / US1/AC7 (partial)+- [X] T063 Add smoke coverage for Session slot controller recording and playback in `tests/Nota.SmokeTest/MidiControllerTests.cs`: record the mod wheel and the pedal into a slot (`RecordSessionSlot`), stop, check `GetSessionController` holds them loop-local; then launch the slot and check `DeliveredController` follows the curve and the pedal value is chased at each loop start. Covers T062's flush, per FR-018 / FR-005 / US1/AC7 (partial)+- [X] T064 Add smoke coverage for routed ("MIDI In") controller capture and count-in controller pickups in `tests/Nota.SmokeTest/MidiControllerTests.cs`. (a) A source track with a clip carrying a CC1 curve routed into an armed destination: recording the destination prints the curve into its take. (b) With a 1-bar count-in, the pedal pressed during the count-in lands before the record start and the take's clip starts earlier to hold it. Per FR-002 / FR-018 (partial)+- [X] T065 Add the v21-project check from contracts/c-abi.md check 10 to `MidiControllerTests.Persistence`: write a minimal v21 `project.json` (no `Controllers` fields) to a temp bundle, `ProjectService.Load` + `Apply`, and assert it loads with no warnings and no controllers, per FR-007 (partial)+- [X] T066 Bring `research.md` up to date with what PR 1 settled: R5 tolerances are CC/pressure 0.008 and wheel 0.012 (not 0.004 / 0.002), the replace-range junction step (`kCtlJunction`), and the held-back last segment between polls (capped at 512 points). R9's `ControllerCurveDto` is parallel `Beats` / `Values` / `Curves?` arrays, rounded on save. "Before the first point no value" belongs in R4. Per plan: research R4/R5/R9 (contradicts)++## Phase 8: Convergence++Re-assessed 2026-10-16 for **PR 1 scope** (Setup, Foundational, US1). PR 1 itself has no+remaining gaps. One finding concerns the US3 tasks that PR 1's design changed underneath them.++- [ ] T067 [US3] Before implementing T043 / T044, re-point them and research R7 at the per-instrument delivered value PR 1 built. There is no `Track::lastCtl_`: the last controller value delivered to an instrument is `Instrument::deliveredCtl[kCtlCount]` (relaxed atomics, NaN = none), written by `deliverExpr` in `src/native/nota.engine/src/Engine_Render.cpp`. `applyAutomation` should compare and update that (store, then call `controller`), and `currentTargetValue` falls back to it, per plan: R7 / data-model Track (contradicts)diff --git a/src/managed/Nota.Application/Engine/EngineContracts.cs b/src/managed/Nota.Application/Engine/EngineContracts.csindex 952789d8..a1d41807 100644--- a/src/managed/Nota.Application/Engine/EngineContracts.cs+++ b/src/managed/Nota.Application/Engine/EngineContracts.cs@@ -301,6 +301,51 @@ public readonly record struct SectionInfo(double StartBeat, double LengthBeats,/// Volume scales the instrument output during the clip.</summary>public enum MidiClipEnvelope { Velocity = 0, Volume = 1 }+/// <summary>Instrument-wide MIDI controllers (specs/020), one id space matching native+/// NOTA_CTL_*: 0..127 the CC, <see cref="PitchWheel"/>, <see cref="ChannelPressure"/>. Values+/// are normalised: a CC 0..1 (data / 127; CC64–69 are switches, on at ≥ 0.5), the wheel −1..+1,+/// pressure 0..1.</summary>+public static class MidiController+{+ public const int PitchWheel = 128;+ public const int ChannelPressure = 129;+ public const int Count = 130;+ public const int ModWheel = 1;+ public const int Sustain = 64;++ /// <summary>Data entry / RPN / NRPN and the channel mode messages: never recorded,+ /// drawn or automated.</summary>+ public static bool IsReserved(int ctl) =>+ ctl < 0 || ctl >= Count || ctl == 6 || ctl == 38 || (ctl >= 96 && ctl <= 101) || (ctl >= 120 && ctl <= 127);++ /// <summary>CC64–69 (sustain, portamento, sostenuto, soft, legato, hold 2): on/off.</summary>+ public static bool IsSwitch(int ctl) => ctl >= 64 && ctl <= 69;++ public static (float Min, float Max) Range(int ctl) => ctl == PitchWheel ? (-1f, 1f) : (0f, 1f);++ private static readonly Dictionary<int, string> Names = new()+ {+ [0] = "Bank select", [1] = "Mod wheel", [2] = "Breath", [4] = "Foot", [5] = "Portamento time",+ [7] = "Volume", [8] = "Balance", [10] = "Pan", [11] = "Expression", [12] = "Effect 1", [13] = "Effect 2",+ [64] = "Sustain", [65] = "Portamento", [66] = "Sostenuto", [67] = "Soft pedal", [68] = "Legato", [69] = "Hold 2",+ [71] = "Resonance", [72] = "Release", [73] = "Attack", [74] = "Brightness", [75] = "Decay",+ [76] = "Vibrato rate", [77] = "Vibrato depth", [78] = "Vibrato delay",+ [84] = "Portamento control", [91] = "Reverb", [92] = "Tremolo", [93] = "Chorus", [94] = "Detune", [95] = "Phaser",+ [PitchWheel] = "Pitch wheel", [ChannelPressure] = "Channel pressure",+ };++ /// <summary>The controller's standard name ("Mod wheel", "Sustain"), or "CC 3" when it has none.</summary>+ public static string Name(int ctl) => Names.TryGetValue(ctl, out var n) ? n : $"CC {ctl}";++ /// <summary>A short label for a lane tab: "Sustain", "Mod wheel", "Pressure", "CC 74".</summary>+ public static string ShortName(int ctl) => ctl switch+ {+ ChannelPressure => "Pressure",+ PitchWheel or ModWheel or Sustain or 2 or 11 => Name(ctl),+ _ => $"CC {ctl}",+ };+}+/// <summary>A per-note expression dimension (MPE). Matches native ExprDim: Bend in semitones/// (the whole-instrument wheel −1..+1), Pressure 0..1, Slide (CC74 timbre) 0..1 with 0.5 neutral.</summary>/// <remarks>Sustain (the CC64 pedal, 0/1) is instrument-wide only — send it with pitch −1.</remarks>diff --git a/src/managed/Nota.Application/Engine/IAudioEngine.cs b/src/managed/Nota.Application/Engine/IAudioEngine.csindex 66737c68..7ac37213 100644--- a/src/managed/Nota.Application/Engine/IAudioEngine.cs+++ b/src/managed/Nota.Application/Engine/IAudioEngine.cs@@ -802,6 +802,12 @@ public interface IAudioEngine : IDisposable/// resets it). Pitch −1 addresses the whole instrument, where Bend is the wheel −1..+1.</summary>void NoteExpression(int pitch, NoteExpressionDim dim, float value);void TrackNoteExpression(int trackId, int pitch, NoteExpressionDim dim, float value);+ /// <summary>A live instrument-wide controller (<see cref="MidiController"/>): plays now and+ /// is recorded into the take. The track form addresses one track.</summary>+ void SendController(int ctl, float value);+ void SendTrackController(int trackId, int ctl, float value);+ /// <summary>The last controller value delivered to the track's instrument; NaN when none.</summary>+ float DeliveredController(int trackId, int ctl);/// <summary>Live notes also reach this track when unarmed (rack/drum pad audition). -1 = none.</summary>void SetAuditionTrack(int trackId);void SetRecording(bool enabled);@@ -1018,6 +1024,15 @@ public interface IAudioEngine : IDisposable/// <summary>MIDI clip envelope (velocity or volume; 0..1, clip-local beats).</summary>AutomationPoint[] GetMidiClipEnvelope(int trackId, int clipIndex, MidiClipEnvelope kind);void SetMidiClipEnvelope(int trackId, int clipIndex, MidiClipEnvelope kind, AutomationPoint[] points);+ /// <summary>The controllers (<see cref="MidiController"/> ids, ascending) a MIDI clip holds+ /// curves for, and each curve (clip-local beats). Set replaces it — empty removes; one undo+ /// step. The Session forms address a slot's clip.</summary>+ int[] GetMidiClipControllers(int trackId, int clipIndex);+ AutomationPoint[] GetMidiClipController(int trackId, int clipIndex, int ctl);+ void SetMidiClipController(int trackId, int clipIndex, int ctl, AutomationPoint[] points);+ int[] GetSessionControllers(int trackId, int scene);+ AutomationPoint[] GetSessionController(int trackId, int scene, int ctl);+ void SetSessionController(int trackId, int scene, int ctl, AutomationPoint[] points);/// <summary>Smoothed real-time DSP load, 0..1 (0 when no live device runs).</summary>float CpuLoad { get; }diff --git a/src/managed/Nota.Infrastructure/Interop/NativeMethods.Tracks.cs b/src/managed/Nota.Infrastructure/Interop/NativeMethods.Tracks.csindex 08801bc7..5c237ca7 100644--- a/src/managed/Nota.Infrastructure/Interop/NativeMethods.Tracks.cs+++ b/src/managed/Nota.Infrastructure/Interop/NativeMethods.Tracks.cs@@ -159,6 +159,24 @@ internal static partial class NativeMethods[LibraryImport(Lib, EntryPoint = "nota_midi_clip_env_set")]internal static partial NotaResult MidiClipEnvSet(IntPtr engine, int trackId, int clipIndex, int kind, [In] AutomationPoint[] points, int count);+ [LibraryImport(Lib, EntryPoint = "nota_midi_clip_ctl_list")]+ internal static partial int MidiClipCtlList(IntPtr engine, int trackId, int clipIndex, [Out] int[]? outCtls, int cap);++ [LibraryImport(Lib, EntryPoint = "nota_midi_clip_ctl_get")]+ internal static partial int MidiClipCtlGet(IntPtr engine, int trackId, int clipIndex, int ctl, [Out] AutomationPoint[]? outPoints, int cap);++ [LibraryImport(Lib, EntryPoint = "nota_midi_clip_ctl_set")]+ internal static partial NotaResult MidiClipCtlSet(IntPtr engine, int trackId, int clipIndex, int ctl, [In] AutomationPoint[] points, int count);++ [LibraryImport(Lib, EntryPoint = "nota_session_ctl_list")]+ internal static partial int SessionCtlList(IntPtr engine, int trackId, int scene, [Out] int[]? outCtls, int cap);++ [LibraryImport(Lib, EntryPoint = "nota_session_ctl_get")]+ internal static partial int SessionCtlGet(IntPtr engine, int trackId, int scene, int ctl, [Out] AutomationPoint[]? outPoints, int cap);++ [LibraryImport(Lib, EntryPoint = "nota_session_ctl_set")]+ internal static partial NotaResult SessionCtlSet(IntPtr engine, int trackId, int scene, int ctl, [In] AutomationPoint[] points, int count);+[LibraryImport(Lib, EntryPoint = "nota_clip_set_warp_markers")]internal static partial NotaResult ClipSetWarpMarkers(IntPtr engine, int trackId, int clipIndex, [In] double[] srcFrames, [In] double[] beats, int count);diff --git a/src/managed/Nota.Infrastructure/Interop/NativeMethods.cs b/src/managed/Nota.Infrastructure/Interop/NativeMethods.csindex 8ee026d9..fda60ea3 100644--- a/src/managed/Nota.Infrastructure/Interop/NativeMethods.cs+++ b/src/managed/Nota.Infrastructure/Interop/NativeMethods.cs@@ -135,6 +135,18 @@ internal static partial class NativeMethods[LibraryImport(Lib, EntryPoint = "nota_track_note_expression")]internal static partial NotaResult TrackNoteExpression(IntPtr engine, int trackId, int pitch, int dim, float value);+ [LibraryImport(Lib, EntryPoint = "nota_engine_controller")]+ internal static partial NotaResult Controller(IntPtr engine, int ctl, float value);++ [LibraryImport(Lib, EntryPoint = "nota_track_controller")]+ internal static partial NotaResult TrackController(IntPtr engine, int trackId, int ctl, float value);++ [LibraryImport(Lib, EntryPoint = "nota_track_delivered_controller")]+ internal static partial float TrackDeliveredController(IntPtr engine, int trackId, int ctl);++ [LibraryImport(Lib, EntryPoint = "nota_engine_midi_ctl_selftest")]+ internal static partial int MidiCtlSelfTest(IntPtr engine);+[LibraryImport(Lib, EntryPoint = "nota_engine_set_audition_track")]internal static partial void SetAuditionTrack(IntPtr engine, int trackId);diff --git a/src/managed/Nota.Infrastructure/Interop/NotaEngine.Tracks.cs b/src/managed/Nota.Infrastructure/Interop/NotaEngine.Tracks.csindex 6a091179..cb07c814 100644--- a/src/managed/Nota.Infrastructure/Interop/NotaEngine.Tracks.cs+++ b/src/managed/Nota.Infrastructure/Interop/NotaEngine.Tracks.cs@@ -236,6 +236,53 @@ public sealed partial class NotaEnginepublic void SetMidiClipEnvelope(int trackId, int clipIndex, MidiClipEnvelope kind, AutomationPoint[] points){ ThrowIfDisposed(); Check(NativeMethods.MidiClipEnvSet(_handle, trackId, clipIndex, (int)kind, points, points.Length)); }+ /// <summary>The controllers a MIDI clip holds curves for (specs/020).</summary>+ public int[] GetMidiClipControllers(int trackId, int clipIndex)+ {+ ThrowIfDisposed();+ int count = NativeMethods.MidiClipCtlList(_handle, trackId, clipIndex, null, 0);+ if (count == 0) return System.Array.Empty<int>();+ var buf = new int[count];+ int written = NativeMethods.MidiClipCtlList(_handle, trackId, clipIndex, buf, count);+ return written == count ? buf : buf[..written];+ }++ public AutomationPoint[] GetMidiClipController(int trackId, int clipIndex, int ctl)+ {+ ThrowIfDisposed();+ int count = NativeMethods.MidiClipCtlGet(_handle, trackId, clipIndex, ctl, null, 0);+ if (count == 0) return System.Array.Empty<AutomationPoint>();+ var buf = new AutomationPoint[count];+ int written = NativeMethods.MidiClipCtlGet(_handle, trackId, clipIndex, ctl, buf, count);+ return written == count ? buf : buf[..written];+ }++ public void SetMidiClipController(int trackId, int clipIndex, int ctl, AutomationPoint[] points)+ { ThrowIfDisposed(); Check(NativeMethods.MidiClipCtlSet(_handle, trackId, clipIndex, ctl, points, points.Length)); }++ public int[] GetSessionControllers(int trackId, int scene)+ {+ ThrowIfDisposed();+ int count = NativeMethods.SessionCtlList(_handle, trackId, scene, null, 0);+ if (count == 0) return System.Array.Empty<int>();+ var buf = new int[count];+ int written = NativeMethods.SessionCtlList(_handle, trackId, scene, buf, count);+ return written == count ? buf : buf[..written];+ }++ public AutomationPoint[] GetSessionController(int trackId, int scene, int ctl)+ {+ ThrowIfDisposed();+ int count = NativeMethods.SessionCtlGet(_handle, trackId, scene, ctl, null, 0);+ if (count == 0) return System.Array.Empty<AutomationPoint>();+ var buf = new AutomationPoint[count];+ int written = NativeMethods.SessionCtlGet(_handle, trackId, scene, ctl, buf, count);+ return written == count ? buf : buf[..written];+ }++ public void SetSessionController(int trackId, int scene, int ctl, AutomationPoint[] points)+ { ThrowIfDisposed(); Check(NativeMethods.SessionCtlSet(_handle, trackId, scene, ctl, points, points.Length)); }+/// <summary>Replaces a warped clip's source↔beat markers (≥2; sorted internally).</summary>public void SetClipWarpMarkers(int trackId, int clipIndex, double[] srcFrames, double[] beats){ ThrowIfDisposed(); Check(NativeMethods.ClipSetWarpMarkers(_handle, trackId, clipIndex, srcFrames, beats, srcFrames.Length)); }diff --git a/src/managed/Nota.Infrastructure/Interop/NotaEngine.cs b/src/managed/Nota.Infrastructure/Interop/NotaEngine.csindex 9ce8d44b..834caf55 100644--- a/src/managed/Nota.Infrastructure/Interop/NotaEngine.cs+++ b/src/managed/Nota.Infrastructure/Interop/NotaEngine.cs@@ -129,6 +129,11 @@ public sealed partial class NotaEngine : IAudioEnginepublic void TrackNoteOff(int trackId, int pitch) { ThrowIfDisposed(); Check(NativeMethods.TrackNoteOff(_handle, trackId, pitch)); }public void NoteExpression(int pitch, NoteExpressionDim dim, float value) { ThrowIfDisposed(); Check(NativeMethods.NoteExpression(_handle, pitch, (int)dim, value)); }public void TrackNoteExpression(int trackId, int pitch, NoteExpressionDim dim, float value) { ThrowIfDisposed(); Check(NativeMethods.TrackNoteExpression(_handle, trackId, pitch, (int)dim, value)); }+ public void SendController(int ctl, float value) { ThrowIfDisposed(); Check(NativeMethods.Controller(_handle, ctl, value)); }+ public void SendTrackController(int trackId, int ctl, float value) { ThrowIfDisposed(); Check(NativeMethods.TrackController(_handle, trackId, ctl, value)); }+ public float DeliveredController(int trackId, int ctl) { ThrowIfDisposed(); return NativeMethods.TrackDeliveredController(_handle, trackId, ctl); }+ /// <summary>Device-free self-test of the clip controller curves (specs/020); 0 = pass.</summary>+ public int MidiCtlSelfTest() { ThrowIfDisposed(); return NativeMethods.MidiCtlSelfTest(_handle); }public void SetAuditionTrack(int trackId) { ThrowIfDisposed(); NativeMethods.SetAuditionTrack(_handle, trackId); }public void SetRecording(bool enabled) { ThrowIfDisposed(); Check(NativeMethods.SetRecording(_handle, enabled ? 1 : 0)); }public bool IsRecording { get { ThrowIfDisposed(); return NativeMethods.IsRecording(_handle) != 0; } }diff --git a/src/managed/Nota.Infrastructure/Persistence/ProjectMigrations.cs b/src/managed/Nota.Infrastructure/Persistence/ProjectMigrations.csindex e7e9a6bb..19fb9908 100644--- a/src/managed/Nota.Infrastructure/Persistence/ProjectMigrations.cs+++ b/src/managed/Nota.Infrastructure/Persistence/ProjectMigrations.cs@@ -91,6 +91,9 @@ public static class ProjectMigrationsif (root["mixer"] is null)root["mixer"] = new JsonObject { ["panLaw"] = "balance", ["panLawLegacy"] = true };}),+ // v21 -> v22: MIDI clips and Session slot clips gain controller curves (Controllers,+ // specs/020). Absent in v21 documents; null = none matches old behaviour — no-op.+ new Migration(21, _ => { }),};/// <summary>Migrates <paramref name="root"/> up to <see cref="ProjectService.CurrentFormatVersion"/>diff --git a/src/managed/Nota.Infrastructure/Persistence/ProjectModel.cs b/src/managed/Nota.Infrastructure/Persistence/ProjectModel.csindex ddabe010..0ad2948d 100644--- a/src/managed/Nota.Infrastructure/Persistence/ProjectModel.cs+++ b/src/managed/Nota.Infrastructure/Persistence/ProjectModel.cs@@ -210,6 +210,40 @@ public sealed class AutomationPointDtopublic AutomationPoint ToPoint() => new(Beat, Value, Curve);}+/// <summary>One controller curve of a MIDI clip (specs/020): the controller (a CC 0..127, 128 the+/// pitch wheel, 129 channel pressure) and its breakpoints in clip-local beats, values normalised.+/// Stored as parallel arrays — a recorded curve can hold a few thousand points, and an object per+/// point would grow a project by ~150 bytes each. Curves is null when every segment is linear.</summary>+public sealed class ControllerCurveDto+{+ public int Ctl { get; set; }+ public double[] Beats { get; set; } = System.Array.Empty<double>();+ public float[] Values { get; set; } = System.Array.Empty<float>();+ public float[]? Curves { get; set; }++ public static ControllerCurveDto From(int ctl, AutomationPoint[] pts)+ {+ var dto = new ControllerCurveDto+ {+ Ctl = ctl,+ Beats = System.Array.ConvertAll(pts, p => Math.Round(p.Beat, 6)),+ Values = System.Array.ConvertAll(pts, p => (float)Math.Round(p.Value, 4)),+ };+ if (System.Array.Exists(pts, p => p.Curve != 0f)) dto.Curves = System.Array.ConvertAll(pts, p => (float)Math.Round(p.Curve, 4));+ return dto;+ }++ public AutomationPoint[] ToPoints()+ {+ int n = Math.Min(Beats.Length, Values.Length);+ var pts = new AutomationPoint[n];+ for (int i = 0; i < n; i++) pts[i] = new AutomationPoint(Beats[i], Values[i], Curves is { } c && i < c.Length ? c[i] : 0f);+ return pts;+ }++ [JsonExtensionData] public Dictionary<string, JsonElement>? Extra { get; set; }+}+public sealed class InstrumentDto{/// <summary>0 = Nota Synth, 1 = Sampler, 2 = Nota Physical, -1 = hosted plugin.</summary>@@ -347,6 +381,7 @@ public sealed class MidiClipDtopublic NoteDto[] Notes { get; set; } = System.Array.Empty<NoteDto>();public AutomationPointDto[]? VelocityEnvelope { get; set; } // clip velocity envelope (v10)public AutomationPointDto[]? VolumeEnvelope { get; set; } // clip volume envelope (v10)+ public ControllerCurveDto[]? Controllers { get; set; } // MIDI controller curves (v22, specs/020)[JsonExtensionData] public Dictionary<string, JsonElement>? Extra { get; set; }}@@ -380,6 +415,7 @@ public sealed class SessionSlotDtopublic int Scene { get; set; }public double LengthBeats { get; set; } = 4.0;public NoteDto[] Notes { get; set; } = System.Array.Empty<NoteDto>();+ public ControllerCurveDto[]? Controllers { get; set; } // MIDI controller curves (v22, specs/020)/// <summary>Set for audio-track slots (a captured take); Notes is empty then.</summary>public AudioClipDto? Audio { get; set; }// Clip properties (Session P0); defaults match a fresh clip.diff --git a/src/managed/Nota.Infrastructure/Persistence/ProjectService.cs b/src/managed/Nota.Infrastructure/Persistence/ProjectService.csindex bec11f28..69093869 100644--- a/src/managed/Nota.Infrastructure/Persistence/ProjectService.cs+++ b/src/managed/Nota.Infrastructure/Persistence/ProjectService.cs@@ -31,7 +31,8 @@ public sealed class ProjectService/// per-segment curvature (automationPoint.curve). v5 adds audio-clip pitch + warp/// (pitchSemitones / warpEnabled / warpMode / warpBeats). v6 adds warp markers.</summary>/// v18 (Phase 3) adds CV modulation: per-track LFO modulators + CV links to device params.- public const int CurrentFormatVersion = 21;+ /// v22 (specs/020) adds MIDI controller curves on MIDI clips and Session slot clips.+ public const int CurrentFormatVersion = 22;/// <summary>Manifest file name inside the bundle folder.</summary>public const string ManifestName = "project.json";@@ -202,6 +203,7 @@ public sealed class ProjectServiceNotes = ToDtos(engine, engine.GetClipNotes(ti.Id, c)),VelocityEnvelope = vel.Length > 0 ? System.Array.ConvertAll(vel, p => new AutomationPointDto(p)) : null,VolumeEnvelope = vol.Length > 0 ? System.Array.ConvertAll(vol, p => new AutomationPointDto(p)) : null,+ Controllers = CaptureControllers(engine.GetMidiClipControllers(ti.Id, c), ctl => engine.GetMidiClipController(ti.Id, c, ctl)),});}}@@ -234,6 +236,7 @@ public sealed class ProjectServiceScene = s,LengthBeats = engine.SessionSlotLength(ti.Id, s),Notes = ToDtos(engine, engine.GetSessionNotes(ti.Id, s)),+ Controllers = CaptureControllers(engine.GetSessionControllers(ti.Id, s), ctl => engine.GetSessionController(ti.Id, s, ctl)),}));}else if (ti.Type == 0 && engine.TryGetSessionAudioSlot(ti.Id, s, out var sa))@@ -639,6 +642,7 @@ public sealed class ProjectServiceengine.SetMidiClipEnvelope(id, ci, MidiClipEnvelope.Velocity, System.Array.ConvertAll(ve, p => p.ToPoint()));if (c.VolumeEnvelope is { Length: > 0 } vo)engine.SetMidiClipEnvelope(id, ci, MidiClipEnvelope.Volume, System.Array.ConvertAll(vo, p => p.ToPoint()));+ ApplyControllers(c.Controllers, warnings, (ctl, pts) => engine.SetMidiClipController(id, ci, ctl, pts));}foreach (var ac in t.AudioClips)@@ -676,6 +680,7 @@ public sealed class ProjectService{engine.AddSessionMidiClip(id, sl.Scene, sl.LengthBeats);if (sl.Notes.Length > 0) engine.SetSessionNotes(id, sl.Scene, ToNotes(engine, sl.Notes));+ ApplyControllers(sl.Controllers, warnings, (ctl, pts) => engine.SetSessionController(id, sl.Scene, ctl, pts));}ApplyClipProps(engine, id, sl);}@@ -1058,6 +1063,34 @@ public sealed class ProjectService}}+ // A clip's controller curves (specs/020); null when it has none, so older files stay alike.+ private static ControllerCurveDto[]? CaptureControllers(int[] ctls, Func<int, AutomationPoint[]> get)+ {+ if (ctls.Length == 0) return null;+ var list = new List<ControllerCurveDto>(ctls.Length);+ foreach (int ctl in ctls)+ {+ var pts = get(ctl);+ if (pts.Length > 0) list.Add(ControllerCurveDto.From(ctl, pts));+ }+ return list.Count > 0 ? list.ToArray() : null;+ }++ private static void ApplyControllers(ControllerCurveDto[]? curves, List<string> warnings, Action<int, AutomationPoint[]> set)+ {+ if (curves is null) return;+ foreach (var cc in curves)+ {+ var pts = cc.ToPoints();+ if (MidiController.IsReserved(cc.Ctl) || pts.Length == 0)+ {+ warnings.Add($"Skipped a clip's controller curve for an unsupported controller ({cc.Ctl}).");+ continue;+ }+ set(cc.Ctl, pts);+ }+ }+private static SessionSlotDto WithClipProps(IAudioEngine engine, int trackId, SessionSlotDto dto){string name = engine.GetSessionClipName(trackId, dto.Scene);diff --git a/src/managed/Nota.Mcp/Tools/MidiTools.cs b/src/managed/Nota.Mcp/Tools/MidiTools.csindex 03c2ca94..93ed3825 100644--- a/src/managed/Nota.Mcp/Tools/MidiTools.cs+++ b/src/managed/Nota.Mcp/Tools/MidiTools.cs@@ -55,6 +55,57 @@ public sealed class MidiTools(IAudioEngine engine, IEngineDispatch dispatch, IArpublic Task TrimClip(int trackId, int clipIndex, double newStartBeat, double newLengthBeats)=> Mutate(() => E.TrimClip(trackId, clipIndex, Math.Max(0, newStartBeat), Math.Max(0.25, newLengthBeats)));+ public sealed record ControllerPoint(+ [property: Description("Beat, relative to the clip start")] double Beat,+ [property: Description("Value: a CC 0..1 (data / 127; sustain and other pedals are down at >= 0.5), the pitch wheel -1..1 (0 = centre), channel pressure 0..1")] float Value);++ public sealed record ClipController(+ [property: Description("Controller id: 0..127 a CC, 128 the pitch wheel, 129 channel pressure")] int Ctl,+ [property: Description("Its name: Sustain, Mod wheel, Pitch wheel, Expression, CC 3, ...")] string Name,+ ControllerPoint[] Points);++ // A controller by number or name: "sustain", "mod_wheel", "pitch_wheel", "channel_pressure", "expression", "64", "cc74".+ private static int ResolveCtl(string ctl)+ {+ var k = ctl.Trim().ToLowerInvariant().Replace(" ", "_");+ if (k.StartsWith("cc")) k = k[2..].TrimStart('_', ' ');+ int id = k switch+ {+ "sustain" or "sustain_pedal" or "pedal" => MidiController.Sustain,+ "mod" or "mod_wheel" or "modwheel" or "modulation" => MidiController.ModWheel,+ "pitch_wheel" or "pitchwheel" or "pitch_bend" or "bend" or "wheel" => MidiController.PitchWheel,+ "channel_pressure" or "pressure" or "aftertouch" => MidiController.ChannelPressure,+ "breath" => 2,+ "expression" => 11,+ _ => int.TryParse(k, out var n) ? n : -1,+ };+ if (MidiController.IsReserved(id))+ throw new ArgumentException($"'{ctl}' is not a controller Nota records (0..127 except 6, 38, 96-101, 120-127; pitch_wheel; channel_pressure).");+ return id;+ }++ [McpServerTool(Name = "get_clip_controllers"), Description(+ "Get a MIDI clip's controller curves — the sustain pedal, mod wheel, pitch wheel, channel pressure and any CC recorded " ++ "with the notes or drawn in the piano roll. Each curve: its controller id and name, and its points (beat in the clip, " ++ "value). Pedals step from point to point; the others glide linearly. Before a curve's first point the controller " ++ "keeps whatever value it had.")]+ public Task<ClipController[]> GetClipControllers(int trackId, int clipIndex) => Read(() =>+ Array.ConvertAll(E.GetMidiClipControllers(trackId, clipIndex), ctl => new ClipController(ctl, MidiController.Name(ctl),+ Array.ConvertAll(E.GetMidiClipController(trackId, clipIndex, ctl), p => new ControllerPoint(p.Beat, p.Value)))));++ [McpServerTool(Name = "set_clip_controller"), Description(+ "Replace one controller curve of a MIDI clip (an empty list removes it); one undo step, heard on the next pass. ctl: a " ++ "CC number (\"64\", \"cc74\") or a name (\"sustain\", \"mod_wheel\", \"pitch_wheel\", \"channel_pressure\", " ++ "\"expression\", \"breath\"). Example — the pedal down on beat 0, up just before the chord change on beat 4: " ++ "[{beat:0,value:1},{beat:3.9,value:0}].")]+ public Task SetClipController(int trackId, int clipIndex, string ctl, ControllerPoint[] points) => Mutate(() =>+ {+ int id = ResolveCtl(ctl);+ var (lo, hi) = MidiController.Range(id);+ E.SetMidiClipController(trackId, clipIndex, id,+ Array.ConvertAll(points, p => new AutomationPoint(Math.Max(-64, p.Beat), Math.Clamp(p.Value, lo, hi))));+ });+public sealed record ClipRef(int TrackId, int ClipIndex);[McpServerTool(Name = "consolidate_clips"), Description(diff --git a/src/native/nota.engine/include/nota/nota_engine.h b/src/native/nota.engine/include/nota/nota_engine.hindex ddc7f501..edb1c1da 100644--- a/src/native/nota.engine/include/nota/nota_engine.h+++ b/src/native/nota.engine/include/nota/nota_engine.h@@ -764,13 +764,47 @@ NOTA_API NotaResult nota_engine_note_off(NotaEngine* engine, int32_t pitch);NOTA_API NotaResult nota_track_note_on(NotaEngine* engine, int32_t track_id, int32_t pitch, float velocity);NOTA_API NotaResult nota_track_note_off(NotaEngine* engine, int32_t track_id, int32_t pitch);/* Per-note expression (MPE) for live notes: dim 0 = pitch bend in semitones, 1 = pressure- * 0..1, 2 = slide (CC74 timbre) 0..1 with 0.5 neutral, 3 = sustain pedal (CC64) 0/1 —+ * 0..1, 2 = slide (CC74 timbre) 0..1 with 0.5 neutral, 3 = sustain pedal (CC64) 0..1 (down at >= 0.5) —* instrument-wide only (pitch -1). pitch -1 addresses the whole instrument; its bend is* the wheel normalized -1..+1 (the synth applies its own range).* A note-on resets the note's expression; send it after the note-on. The engine_ form* reaches the tracks live notes reach; the track_ form one track (Nota Remote). */NOTA_API NotaResult nota_engine_note_expression(NotaEngine* engine, int32_t pitch, int32_t dim, float value);NOTA_API NotaResult nota_track_note_expression(NotaEngine* engine, int32_t track_id, int32_t pitch, int32_t dim, float value);++/* ---- MIDI controllers (specs/020) ----------------------------------------+ * Instrument-wide controllers, one id space: ctl 0..127 = that CC, NOTA_CTL_PITCH_WHEEL,+ * NOTA_CTL_CHANNEL_PRESSURE. Values are normalised: a CC 0..1 (data / 127; CC64-69 are+ * switches, on at >= 0.5), the wheel -1..+1 (centre 0), pressure 0..1. Data entry / RPN /+ * NRPN (6, 38, 96-101) and channel mode (120-127) are reserved: refused everywhere.+ * The instrument-wide expression above (pitch -1, dim 0..3) is the wheel / pressure / CC74 /+ * CC64 of this space. */+#define NOTA_CTL_PITCH_WHEEL 128+#define NOTA_CTL_CHANNEL_PRESSURE 129+#define NOTA_CTL_COUNT 130+/* Live controller input, like note_on: the engine_ form reaches the tracks live notes reach,+ * the track_ form one track. Plays now and is recorded into the take when it records. Safe+ * from any thread. */+NOTA_API NotaResult nota_engine_controller(NotaEngine* engine, int32_t ctl, float value);+NOTA_API NotaResult nota_track_controller(NotaEngine* engine, int32_t track_id, int32_t ctl, float value);+/* The last value the engine delivered to the track's instrument for `ctl` (live, clip or+ * automation), NaN when none since the instrument was created. A read for tests and meters. */+NOTA_API float nota_track_delivered_controller(const NotaEngine* engine, int32_t track_id, int32_t ctl);+/* A MIDI clip's controller curves (clip-local beats; may start before 0 like a pickup note).+ * list fills the ctls holding data (ascending) and returns their count (out may be NULL).+ * get(out=NULL) returns the point count. set replaces the curve (count 0 removes it; points+ * in any order, the last one given per beat kept); one undo step, plays from the next block. */+NOTA_API int32_t nota_midi_clip_ctl_list(const NotaEngine* engine, int32_t track_id, int32_t clip_index, int32_t* out_ctls, int32_t cap);+NOTA_API int32_t nota_midi_clip_ctl_get(const NotaEngine* engine, int32_t track_id, int32_t clip_index, int32_t ctl, NotaAutomationPoint* out, int32_t cap);+NOTA_API NotaResult nota_midi_clip_ctl_set(NotaEngine* engine, int32_t track_id, int32_t clip_index, int32_t ctl, const NotaAutomationPoint* pts, int32_t count);+/* The same for a Session slot's clip (beats in [0, slot length)). */+NOTA_API int32_t nota_session_ctl_list(const NotaEngine* engine, int32_t track_id, int32_t scene, int32_t* out_ctls, int32_t cap);+NOTA_API int32_t nota_session_ctl_get(const NotaEngine* engine, int32_t track_id, int32_t scene, int32_t ctl, NotaAutomationPoint* out, int32_t cap);+NOTA_API NotaResult nota_session_ctl_set(NotaEngine* engine, int32_t track_id, int32_t scene, int32_t ctl, const NotaAutomationPoint* pts, int32_t count);+/* Device-free self-test of controller curves: value at a beat (switch + linear), split / slice,+ * chase and end-of-clip release on the playback wire, the recording fold (overdub touched+ * range). 0 = pass, else the number of the first failed check. */+NOTA_API int32_t nota_engine_midi_ctl_selftest(NotaEngine* engine);/* Audition target: live notes also reach this track even when unarmed (rack/drum* pad preview). Pass -1 to clear. */NOTA_API void nota_engine_set_audition_track(NotaEngine* engine, int32_t track_id);diff --git a/src/native/nota.engine/pluginhost/PluginHost.cpp b/src/native/nota.engine/pluginhost/PluginHost.cppindex 5168c870..7351b385 100644--- a/src/native/nota.engine/pluginhost/PluginHost.cpp+++ b/src/native/nota.engine/pluginhost/PluginHost.cpp@@ -705,20 +705,24 @@ public:void allNotesOff() override {pending_.addEvent(juce::MidiMessage::allNotesOff(1), 0);}- // Expression reaches a plugin as plain channel-1 MIDI: the instrument-wide wheel /- // channel pressure / CC74, and a note's pressure as polyphonic aftertouch. (Per-note- // bend and slide would need the plugin's own MPE channel layout — not sent.)+ // Expression reaches a plugin as plain channel-1 MIDI: a note's pressure as polyphonic+ // aftertouch. (Per-note bend and slide would need the plugin's own MPE channel layout —+ // not sent.) The instrument-wide wheel / pressure / CCs arrive through controller().void noteExpression(int32_t pitch, int32_t dim, float value) override {- auto u7 = [](float v) { return juce::jlimit(0, 127, (int)std::lround(v * 127.0f)); };- if (pitch < 0) {- if (dim == 0) pending_.addEvent(juce::MidiMessage::pitchWheel(1, juce::jlimit(0, 16383, (int)std::lround((value + 1.0f) * 8191.5f))), 0);- else if (dim == 1) pending_.addEvent(juce::MidiMessage::channelPressureChange(1, u7(value)), 0);- else if (dim == 2) pending_.addEvent(juce::MidiMessage::controllerEvent(1, 74, u7(value)), 0);- else if (dim == 3) pending_.addEvent(juce::MidiMessage::controllerEvent(1, 64, value >= 0.5f ? 127 : 0), 0);- } else if (dim == 1) {+ if (pitch >= 0 && dim == 1)pending_.addEvent(juce::MidiMessage::aftertouchChange(1, pitch, u7(value)), 0);- }}+ // Every controller as the MIDI message itself (specs/020): any CC with its real value+ // (the sustain pedal too, so a piano can half-pedal), the 14-bit wheel, channel pressure.+ void controller(int32_t ctl, float value) override {+ if (ctl == nota::kCtlPitchWheel)+ pending_.addEvent(juce::MidiMessage::pitchWheel(1, juce::jlimit(0, 16383, (int)std::lround((value + 1.0f) * 8191.5f))), 0);+ else if (ctl == nota::kCtlChannelPressure)+ pending_.addEvent(juce::MidiMessage::channelPressureChange(1, u7(value)), 0);+ else if (ctl >= 0 && ctl < 128)+ pending_.addEvent(juce::MidiMessage::controllerEvent(1, ctl, u7(value)), 0);+ }+ static int u7(float v) { return juce::jlimit(0, 127, (int)std::lround(v * 127.0f)); }void render(float* out, int32_t frames) override {if (frames <= 0 || frames > maxBlock_ || plugin_ == nullptr) return;diff --git a/src/native/nota.engine/src/BassSynth.h b/src/native/nota.engine/src/BassSynth.hindex a1a8466f..7558d1ba 100644--- a/src/native/nota.engine/src/BassSynth.h+++ b/src/native/nota.engine/src/BassSynth.h@@ -83,6 +83,11 @@ public:int32_t kind() const override { return 7; }const char* displayName() const override { return "Nota Bass"; }+ // The mod wheel (CC1) moves the Mod Wheel control, as a learned knob would (specs/020).+ void controller(int32_t ctl, float value) override {+ if (ctl == kCtlModWheel) pn_[ModWheel].store(std::clamp(value, 0.0f, 1.0f), std::memory_order_relaxed);+ Instrument::controller(ctl, value);+ }void setSampleRate(double sr) override { sampleRate_ = sr > 0 ? sr : 44100.0; }// ---- parameters -------------------------------------------------------diff --git a/src/native/nota.engine/src/Consort.h b/src/native/nota.engine/src/Consort.hindex ba772211..6e5d9c59 100644--- a/src/native/nota.engine/src/Consort.h+++ b/src/native/nota.engine/src/Consort.h@@ -282,6 +282,11 @@ public:const char* displayName() const override { return "Nota Consort"; }// Deferred to the audio thread (render) so a device-rate change can't race a render.+ // The mod wheel (CC1) moves the Mod Wheel control, as a learned knob would (specs/020).+ void controller(int32_t ctl, float value) override {+ if (ctl == kCtlModWheel) pn_[ModWheel].store(std::clamp(value, 0.0f, 1.0f), std::memory_order_relaxed);+ Instrument::controller(ctl, value);+ }void setSampleRate(double sr) override { pendingRate_.store(sr > 0 ? sr : 44100.0, std::memory_order_relaxed); }int32_t activeVoiceCount() const override { return static_cast<int32_t>(tele_[ScActive].load(std::memory_order_relaxed)); }diff --git a/src/native/nota.engine/src/Engine.h b/src/native/nota.engine/src/Engine.hindex ee39548e..78503a89 100644--- a/src/native/nota.engine/src/Engine.h+++ b/src/native/nota.engine/src/Engine.h@@ -59,6 +59,11 @@ using RecordedQueue = SpscRingBuffer<RecordedNote, 1024>;// and start (as its RecordedNote will carry them), `beat` is the offset from that start.struct RecordedExpr { int32_t pitch; double startBeat; int32_t dim; float beat; float value; };using RecordedExprQueue = SpscRingBuffer<RecordedExpr, 1u << 14>;+// A recorded controller sample (audio -> message): at an absolute beat of the take (a Session+// take: loop-local), in loop pass `pass`. ctl -1 is a pass-end marker at `beat` (the loop end):+// controllers still being replaced over a range stop there (specs/020, FR-021).+struct RecordedCtl { int32_t ctl; double beat; float value; int32_t pass; };+using RecordedCtlQueue = SpscRingBuffer<RecordedCtl, 1u << 14>;// A clip note's expression at a sample offset of the block (the render pass replays these).struct ExprEv { int32_t off; int32_t pitch; int32_t dim; float value; };@@ -260,6 +265,13 @@ public:// MIDI clip envelopes (kind: 0 = velocity, 1 = volume; 0..1 in clip-local beats).int32_t getMidiClipEnvelope(int32_t trackId, int32_t clipIndex, int32_t kind, NotaAutomationPoint* out, int32_t cap) const;bool setMidiClipEnvelope(int32_t trackId, int32_t clipIndex, int32_t kind, const NotaAutomationPoint* pts, int32_t count);+ // Clip controller curves (specs/020). slot: false = arrangement clip `index`, true = the+ // Session slot of scene `index`. set: count 0 removes the curve; one undo step.+ int32_t ctlList(int32_t trackId, bool slot, int32_t index, int32_t* out, int32_t cap) const;+ int32_t ctlGet(int32_t trackId, bool slot, int32_t index, int32_t ctl, NotaAutomationPoint* out, int32_t cap) const;+ bool ctlSet(int32_t trackId, bool slot, int32_t index, int32_t ctl, const NotaAutomationPoint* pts, int32_t count);+ float deliveredController(int32_t trackId, int32_t ctl) const;+ int32_t midiCtlSelfTest();// --- hosted-plugin parameter automation (M9-B) ---// deviceIndex < 0 = the track's instrument; otherwise the effect at that index.@@ -979,6 +991,10 @@ public:// Per-note expression for live notes (MPE, NoteExpression.h): dim = ExprDim, pitch −1 =// the whole instrument. Reaches the same tracks as live notes do.void noteExpression(int32_t pitch, int32_t dim, float value);+ // Instrument-wide MIDI controller (specs/020, MidiController.h), live: like a note, to the+ // armed / audition tracks (or one track), and recorded when the take records. Any thread.+ void controller(int32_t ctl, float value);+ void trackController(int32_t trackId, int32_t ctl, float value);// Live notes addressed to one track (Nota Remote). Callable from any thread: producers// serialize on remoteMidiMx_; the audio thread only pops (AR-6).void trackNoteOn(int32_t trackId, int32_t pitch, float velocity);@@ -1182,6 +1198,7 @@ private:void mpeNoteOn(int32_t pitch, float velocity) override { e->noteOn(pitch, velocity); }void mpeNoteOff(int32_t pitch) override { e->noteOff(pitch); }void mpeExpression(int32_t pitch, int32_t dim, float value) override { e->noteExpression(pitch, dim, value); }+ void mpeController(int32_t ctl, float value) override { e->controller(ctl, value); }};MpeSink mpeSink_;std::array<MpeInput, MidiInput::kMaxSources> mpeInputs_;@@ -1199,6 +1216,7 @@ private:std::mutex remoteMidiMx_; // producer side onlyRecordedQueue recorded_;RecordedExprQueue recordedExpr_;+ RecordedCtlQueue recordedCtl_;mutable std::mutex exprMx_; // the expression storestd::unordered_map<int32_t, std::shared_ptr<const NoteExpr>> exprStore_;int32_t nextExprId_ = 1;@@ -1373,6 +1391,38 @@ private:struct TakeNote { int32_t pitch; double absStart; int32_t pass; };std::vector<TakeNote> takeNotes_;int32_t appliedReplaceUpTo_ = 0;+ // Recorded controllers folding into the take (message thread, specs/020). Each controller a+ // pass moves is replaced over the range it touched — from its first point in the pass to the+ // pass end (or the record stop) — so overdubbing a controller never interleaves two takes of+ // it; controllers it didn't move, and the notes, stay.+ struct CtlFold {+ std::vector<RecordedCtl> run; // this range's points since the last commit+ bool open = false; // a replace range is running+ int32_t pass = 0;+ double startAbs = 0.0; // range start (take beats)+ double lastAbs = 0.0; // the range's latest point (take beats)+ bool hasCommitted = false;+ AutomationPoint committed{}; // the range's last committed point (take beats)+ std::shared_ptr<const ControllerCurve> before; // the clip's curve when the range opened+ };+ std::array<CtlFold, kCtlCount> ctlFold_{};+ std::vector<RecordedCtl> ctlBatch_; // drained this poll, in arrival order+ bool ctlStopPending_ = false; // the take stopped: close the open ranges there+ double ctlStopAt_ = 0.0;+ struct TakeCtl { int32_t ctl; double absBeat; int32_t pass; }; // committed by this take+ std::vector<TakeCtl> takeCtls_;+ void resetCtlFold();+ // Fold ctlBatch_ (and a pending stop) into the take's clip. clipStartAbs is the clip's start+ // on the take clock (0 for a Session slot, whose take is loop-local over slotLen). Returns+ // true when the clip changed.+ bool foldRecordedCtl(MidiClip& clip, double slotLen);+ // final: the range ends here, commit every point; otherwise a moving curve keeps its last+ // thinned segment back for the next poll, so thinning spans polls (one gesture, few points).+ void commitCtlRun(MidiClip& clip, int32_t ctl, double slotLen, bool final);+ void closeCtlRange(MidiClip& clip, int32_t ctl, double atAbs, double slotLen);+ // A take that ends without a record stop (a Session slot take finalised, the record track+ // disarmed): fold what is still queued or held back into it now, while its target is known.+ void flushCtlTake();std::atomic<double> uiCountIn_{0.0}; // beats of count-in left (UI mirror)// False while a count-in runs: takes started from stop don't capture the clicks-only// pre-roll (the hardware tap and the internal-resampling tap both honour it).@@ -1537,6 +1587,15 @@ private:// Clip-note expression replayed per block (computeBlockMidi fills, the render pass merges),// per track position like blockMidi_.static constexpr int kMaxBlockExpr = 1024;+ // A clip's controller curves on the playback wire for one block (specs/020): the value at the+ // clip's start or at a jump into it (chase), every point inside the block, and a value every+ // 64 samples while a curve moves. Times are in samples on the block's clock.+ static void clipCtlEvents(const MidiClip& clip, double clipStartS, double clipEndS, double blockStart,+ int32_t frames, double spb, bool chase, ExprEv* out, int& n, int cap);+ // At a clip's end, the pedals it holds down and a bent wheel go back to rest — no note stays+ // held by a clip that is over.+ static void clipCtlEndResets(const MidiClip& clip, double clipStartS, double clipEndS, double blockStart,+ int32_t frames, ExprEv* out, int& n, int cap);std::vector<std::vector<ExprEv>> blockExpr_;std::vector<int> blockExprN_;// Appends a clip note's recorded expression for the block: the note sounds over@@ -1616,6 +1675,15 @@ private:// routing, so the piano roll can highlight the key you're pressing. 128 bits, set/cleared// on noteOn/noteOff (message/CoreMIDI thread), read lock-free by the UI.std::atomic<uint32_t> liveHeld_[4]{};+ // Every live controller's latest value and a count of its moves (any producer thread+ // writes, the audio thread seeds takes from it, the message thread starts automation+ // writes from it). Values start at rest.+ std::atomic<float> liveCtl_[kCtlCount]{};+ std::atomic<uint32_t> liveCtlTouch_[kCtlCount]{};+ void noteLiveController(int32_t ctl, float value) {+ liveCtl_[ctl].store(value, std::memory_order_relaxed);+ liveCtlTouch_[ctl].fetch_add(1, std::memory_order_relaxed);+ }// instrument render scratch (pre-allocated, big enough for any device block).static constexpr int32_t kMaxBlock = 16384;diff --git a/src/native/nota.engine/src/Engine_Automation.cpp b/src/native/nota.engine/src/Engine_Automation.cppindex 7752783d..a56f3362 100644--- a/src/native/nota.engine/src/Engine_Automation.cpp+++ b/src/native/nota.engine/src/Engine_Automation.cpp@@ -17,6 +17,7 @@#include <algorithm>#include <chrono>+#include <limits>#include <cmath>namespace nota {@@ -763,4 +764,142 @@ bool Engine::setMidiClipEnvelope(int32_t trackId, int32_t clipIndex, int32_t kinreturn true;}+// --- clip controller curves (specs/020) ---------------------------------------+static const MidiClip* ctlClipOf(const Track& t, bool slot, int32_t index) {+ if (slot) {+ if (index < 0 || index >= static_cast<int32_t>(t.sessionSlots.size()) || !t.sessionSlots[index].hasClip) return nullptr;+ return &t.sessionSlots[index].midi;+ }+ if (index < 0 || index >= static_cast<int32_t>(t.midiClips.size())) return nullptr;+ return &t.midiClips[index];+}++int32_t Engine::ctlList(int32_t trackId, bool slot, int32_t index, int32_t* out, int32_t cap) const {+ auto t = findTrackAuthoring(trackId);+ const MidiClip* c = t ? ctlClipOf(*t, slot, index) : nullptr;+ if (!c) return 0;+ int32_t n = 0;+ for (const auto& cv : c->controllers) {+ if (!cv) continue;+ if (out && n < cap) out[n] = cv->ctl;+ ++n;+ }+ return out ? std::min(n, cap) : n;+}++int32_t Engine::ctlGet(int32_t trackId, bool slot, int32_t index, int32_t ctl, NotaAutomationPoint* out, int32_t cap) const {+ auto t = findTrackAuthoring(trackId);+ const MidiClip* c = t ? ctlClipOf(*t, slot, index) : nullptr;+ const ControllerCurve* cv = c ? c->controller(ctl) : nullptr;+ if (!cv) return 0;+ const auto& pts = cv->points;+ if (!out) return static_cast<int32_t>(pts.size());+ const int32_t n = std::min<int32_t>(cap, static_cast<int32_t>(pts.size()));+ for (int32_t i = 0; i < n; ++i) { out[i].beat = pts[i].beat; out[i].value = pts[i].value; out[i].curve = pts[i].curve; }+ return n;+}++bool Engine::ctlSet(int32_t trackId, bool slot, int32_t index, int32_t ctl, const NotaAutomationPoint* pts, int32_t count) {+ if (ctlIsReserved(ctl) || count < 0 || (count > 0 && !pts)) return false;+ auto old = findTrackAuthoring(trackId);+ if (!old || !ctlClipOf(*old, slot, index)) return false;+ auto nt = cloneTrack(*old);+ MidiClip& c = slot ? nt->sessionSlots[index].midi : nt->midiClips[index];+ std::vector<AutomationPoint> p;+ p.reserve(count);+ for (int32_t i = 0; i < count; ++i)+ p.push_back({ pts[i].beat, ctlClamp(ctl, pts[i].value), std::clamp(pts[i].curve, -1.0f, 1.0f) });+ c.setController(ctl, std::move(p));+ republishWithTrack(trackId, nt);+ return true;+}++float Engine::deliveredController(int32_t trackId, int32_t ctl) const {+ if (ctl < 0 || ctl >= kCtlCount) return std::numeric_limits<float>::quiet_NaN();+ auto t = findTrackAuthoring(trackId);+ if (!t || !t->instrument) return std::numeric_limits<float>::quiet_NaN();+ return t->instrument->deliveredCtl[ctl].load(std::memory_order_relaxed);+}++// Device-free checks of the controller curves (specs/020): numbered, 0 = pass. Runs on the+// message thread with private state (the fold scratch is saved and restored).+int32_t Engine::midiCtlSelfTest() {+ auto near = [](float a, float b) { return std::fabs(a - b) < 1e-3f; };+ ControllerCurve sus; sus.ctl = kCtlSustain; sus.points = { { 1.0, 1.0f, 0.0f }, { 3.0, 0.0f, 0.0f } };+ ControllerCurve mod; mod.ctl = kCtlModWheel; mod.points = { { 0.0, 0.0f, 0.0f }, { 2.0, 1.0f, 0.0f } };+ // 1-2: value at a beat — a switch steps, the rest interpolate.+ if (!near(sus.valueAt(2.0), 1.0f) || !near(sus.valueAt(2.999), 1.0f) || !near(sus.valueAt(3.5), 0.0f)) return 1;+ if (!near(mod.valueAt(1.0), 0.5f) || !near(mod.valueAt(5.0), 1.0f)) return 2;+ // 3: a slice pins the value at its start, keeps its points, drops the rest.+ {+ auto p = sliceCtlPoints(sus, 2.0, 4.0);+ if (p.size() != 2 || !near(p[0].value, 1.0f) || p[0].beat != 0.0 || p[1].beat != 1.0 || !near(p[1].value, 0.0f)) return 3;+ if (!sliceCtlPoints(sus, 0.0, 0.5).empty()) return 3; // before its first point: nothing+ }+ // 4: the playback wire — a clip starting in the block sends its values from there; a switch+ // whose first point lies later sends nothing until it; points land on their sample.+ {+ MidiClip c; c.lengthBeats = 4.0;+ c.setController(kCtlSustain, sus.points);+ c.setController(kCtlModWheel, mod.points);+ ExprEv ev[256]; int n = 0;+ clipCtlEvents(c, 0.0, 400.0, 0.0, 256, 100.0, false, ev, n, 256); // spb 100: beat 1 = sample 100+ bool modStart = false, susAt100 = false, susAtStart = false, modMoves = false;+ for (int i = 0; i < n; ++i) {+ if (ev[i].dim == kCtlDimBase + kCtlModWheel && ev[i].off == 0 && near(ev[i].value, 0.0f)) modStart = true;+ if (ev[i].dim == kCtlDimBase + kCtlModWheel && ev[i].off == 128 && near(ev[i].value, 0.64f)) modMoves = true;+ if (ev[i].dim == kCtlDimBase + kCtlSustain && ev[i].off == 100 && near(ev[i].value, 1.0f)) susAt100 = true;+ if (ev[i].dim == kCtlDimBase + kCtlSustain && ev[i].off == 0) susAtStart = true;+ }+ if (!modStart || !susAt100 || susAtStart || !modMoves) return 4;+ // 5: chase — a jump to beat 2.5 sends the pedal down and the wheel up there.+ n = 0;+ clipCtlEvents(c, 0.0, 400.0, 250.0, 64, 100.0, true, ev, n, 256);+ bool chSus = false, chMod = false;+ for (int i = 0; i < n; ++i) {+ if (ev[i].off == 0 && ev[i].dim == kCtlDimBase + kCtlSustain && near(ev[i].value, 1.0f)) chSus = true;+ if (ev[i].off == 0 && ev[i].dim == kCtlDimBase + kCtlModWheel && near(ev[i].value, 1.0f)) chMod = true;+ }+ if (!chSus || !chMod) return 5;+ // 6: a clip that ends with the pedal down releases it there; the mod wheel stays.+ MidiClip d; d.lengthBeats = 2.0;+ d.setController(kCtlSustain, { { 0.0, 1.0f, 0.0f } });+ d.setController(kCtlModWheel, { { 0.0, 0.7f, 0.0f } });+ n = 0;+ clipCtlEndResets(d, 0.0, 200.0, 150.0, 100, ev, n, 256);+ if (n != 1 || ev[0].off != 50 || ev[0].dim != kCtlDimBase + kCtlSustain || ev[0].value != kCtlRest) return 6;+ }+ // 7-8: the recording fold.+ auto savedFold = ctlFold_; auto savedBatch = ctlBatch_; auto savedTake = takeCtls_;+ const bool savedStop = ctlStopPending_; const double savedStopAt = ctlStopAt_;+ int32_t fail = 0;+ {+ // 7: overdub — pass 1 moves the mod wheel from beat 2: it replaces from there to the+ // pass end; pass 0's earlier point stays.+ for (auto& f : ctlFold_) f = CtlFold{};+ ctlBatch_.clear(); takeCtls_.clear(); ctlStopPending_ = false;+ MidiClip c; c.lengthBeats = 4.0;+ c.setController(kCtlModWheel, { { 0.2, 0.3f, 0.0f }, { 2.5, 0.3f, 0.0f }, { 3.5, 0.1f, 0.0f } });+ ctlBatch_ = { { kCtlModWheel, 2.0, 0.9f, 1 }, { kCtlModWheel, 3.0, 0.9f, 1 }, { -1, 4.0, 0.0f, 1 } };+ foldRecordedCtl(c, 0.0);+ const ControllerCurve* m = c.controller(kCtlModWheel);+ if (!m || !near(m->valueAt(1.0), 0.3f) || !near(m->valueAt(3.0), 0.9f) || !near(m->valueAt(3.8), 0.9f)) fail = 7;+ // 8: a take that stops at beat 4 hands back to what the clip held after it.+ if (!fail) {+ for (auto& f : ctlFold_) f = CtlFold{};+ MidiClip e; e.lengthBeats = 8.0;+ e.setController(kCtlModWheel, { { 0.0, 0.2f, 0.0f }, { 6.0, 0.2f, 0.0f } });+ ctlBatch_ = { { kCtlModWheel, 2.0, 0.8f, 0 }, { kCtlModWheel, 3.0, 0.8f, 0 } };+ ctlStopPending_ = true; ctlStopAt_ = 4.0;+ foldRecordedCtl(e, 0.0);+ const ControllerCurve* w = e.controller(kCtlModWheel);+ if (!w || !near(w->valueAt(1.0), 0.2f) || !near(w->valueAt(2.5), 0.8f) || !near(w->valueAt(4.0), 0.2f) || !near(w->valueAt(7.0), 0.2f))+ fail = 8;+ }+ }+ ctlFold_ = savedFold; ctlBatch_ = savedBatch; takeCtls_ = savedTake;+ ctlStopPending_ = savedStop; ctlStopAt_ = savedStopAt;+ return fail;+}+} // namespace notadiff --git a/src/native/nota.engine/src/Engine_Recording.cpp b/src/native/nota.engine/src/Engine_Recording.cppindex f6c722dd..943857de 100644--- a/src/native/nota.engine/src/Engine_Recording.cpp+++ b/src/native/nota.engine/src/Engine_Recording.cpp@@ -30,6 +30,7 @@ void Engine::setTrackArmed(int32_t trackId, bool armed) {// materialised / MIDI capture stops), so toggling its REC button stops the recording.if (audioRecording_ && trackId == audioRecordTrackId_) stopAudioRecording();if (recording_.load(std::memory_order_relaxed) && trackId == recordTrackId_) {+ flushCtlTake(); // the take's controllers still in flight (specs/020)recordTrackId_ = -1;recordTrackRt_.store(-1, std::memory_order_relaxed);recordClipIndex_ = -1;@@ -161,9 +162,20 @@ void Engine::noteOff(int32_t pitch) {liveHeld_[pitch >> 5].fetch_and(~(1u << (pitch & 31)), std::memory_order_relaxed);}+// The instrument-wide dims (pitch −1) are controllers now: one path plays and records them.+static int32_t ctlOfGlobalDim(int32_t dim) {+ switch (dim) {+ case ExprBend: return kCtlPitchWheel;+ case ExprPressure: return kCtlChannelPressure;+ case ExprSlide: return 74;+ default: return kCtlSustain; // ExprSustain+ }+}+void Engine::noteExpression(int32_t pitch, int32_t dim, float value) {if (pitch < -1 || pitch > 127 || dim < 0 || dim >= kExprWireDims || (dim >= kExprDims && pitch >= 0)|| !std::isfinite(value)) return;+ if (pitch < 0) { controller(ctlOfGlobalDim(dim), value); return; }std::lock_guard<std::mutex> lk(liveMidiMx_);liveMidi_.push(MidiEvent{false, pitch, value, -1, dim});}@@ -171,10 +183,27 @@ void Engine::noteExpression(int32_t pitch, int32_t dim, float value) {void Engine::trackNoteExpression(int32_t trackId, int32_t pitch, int32_t dim, float value) {if (pitch < -1 || pitch > 127 || dim < 0 || dim >= kExprWireDims || (dim >= kExprDims && pitch >= 0)|| !std::isfinite(value)) return;+ if (pitch < 0) { trackController(trackId, ctlOfGlobalDim(dim), value); return; }std::lock_guard<std::mutex> lk(remoteMidiMx_);remoteMidi_.push(MidiEvent{false, pitch, value, trackId, dim});}+void Engine::controller(int32_t ctl, float value) {+ if (ctlIsReserved(ctl) || !std::isfinite(value)) return;+ value = ctlClamp(ctl, value);+ noteLiveController(ctl, value);+ std::lock_guard<std::mutex> lk(liveMidiMx_);+ liveMidi_.push(MidiEvent{false, -1, value, -1, kCtlDimBase + ctl});+}++void Engine::trackController(int32_t trackId, int32_t ctl, float value) {+ if (ctlIsReserved(ctl) || !std::isfinite(value)) return;+ value = ctlClamp(ctl, value);+ noteLiveController(ctl, value);+ std::lock_guard<std::mutex> lk(remoteMidiMx_);+ remoteMidi_.push(MidiEvent{false, -1, value, trackId, kCtlDimBase + ctl});+}+void Engine::trackNoteOn(int32_t trackId, int32_t pitch, float velocity) {{std::lock_guard<std::mutex> lk(remoteMidiMx_);@@ -248,8 +277,10 @@ void Engine::setRecording(bool on) {// when no track is armed for a take — if the UI then pops the button back up// it calls us again with false, which clears it.setAutomationRecord(on);- if (on) { collectRecordedExpr(); pendingExpr_.clear(); } // a new take starts with no stale curves+ if (on) { collectRecordedExpr(); pendingExpr_.clear(); resetCtlFold(); } // a new take starts with no stale curvesif (!on) {+ // Controllers still being replaced over a range end where the take stops (poll folds it).+ if (recording_.load(std::memory_order_relaxed)) { ctlStopPending_ = true; ctlStopAt_ = transport_.uiPositionBeats(); }recording_.store(false, std::memory_order_relaxed);stopAudioRecording(); // materialise if an audio take was rolling// If the take started the transport, stop it and rewind to where thediff --git a/src/native/nota.engine/src/Engine_Render.cpp b/src/native/nota.engine/src/Engine_Render.cppindex db156bbf..9ae36853 100644--- a/src/native/nota.engine/src/Engine_Render.cpp+++ b/src/native/nota.engine/src/Engine_Render.cpp@@ -116,6 +116,31 @@ inline bool midiEvLess(const MidiEv& a, const MidiEv& b) {return a.off < b.off || (a.off == b.off && !a.on && b.on);}+// Stop / jump: pedals left down and a bent wheel go back to rest (the chase that follows a jump+// sets them again where the clip has them).+inline void releaseHeldControllers(Instrument& inst) {+ for (int32_t ctl : { 64, 65, 66, 67, 68, 69, static_cast<int32_t>(kCtlPitchWheel) }) {+ const float v = inst.deliveredCtl[ctl].load(std::memory_order_relaxed);+ if (std::isnan(v) || v == kCtlRest) continue;+ inst.deliveredCtl[ctl].store(kCtlRest, std::memory_order_relaxed);+ inst.controller(ctl, kCtlRest);+ }+}++// One expression-wire value into an instrument: a controller (dim >= kCtlDimBase, pitch −1)+// or a note's / the instrument's expression. Controllers are remembered on the instrument for+// the stop reset.+inline void deliverExpr(Instrument& inst, int32_t pitch, int32_t dim, float value) {+ if (dim >= kCtlDimBase) {+ const int32_t ctl = dim - kCtlDimBase;+ if (ctl < 0 || ctl >= kCtlCount) return;+ inst.deliveredCtl[ctl].store(value, std::memory_order_relaxed);+ inst.controller(ctl, value);+ } else {+ inst.noteExpression(pitch, dim, value);+ }+}+// Drive an instrument through one block: note events and clip-note expression merged by// sample offset (notes first at a shared offset, so a note's opening expression lands on it),// rendering the stretches in between. `live` runs once, before the first sample is rendered —@@ -142,7 +167,7 @@ void playEvents(Instrument& inst, float* dst, int32_t frames, const MidiEv* evs,++k;} else {renderTo(xOff);- inst.noteExpression(xev[x].pitch, xev[x].dim, xev[x].value);+ deliverExpr(inst, xev[x].pitch, xev[x].dim, xev[x].value);++x;}}@@ -173,6 +198,52 @@ void Engine::noteExprEvents(const Note& note, double onS, double offS, int32_t f}}+void Engine::clipCtlEvents(const MidiClip& clip, double clipStartS, double clipEndS, double blockStart,+ int32_t frames, double spb, bool chase, ExprEv* out, int& n, int cap) {+ static constexpr int32_t kStep = 64; // as recorded MPE: the instrument smooths between+ if (clip.controllers.empty() || spb <= 0.0) return;+ const double b1 = blockStart + frames;+ const double from = std::max(blockStart, clipStartS), to = std::min(b1, clipEndS);+ if (to <= from) return;+ const int32_t first = static_cast<int32_t>(from - blockStart);+ const int32_t end = std::min(frames, static_cast<int32_t>(std::ceil(to - blockStart)));+ const bool entry = chase || (clipStartS >= blockStart - 0.5 && clipStartS < b1 - 0.5); // half-sample slack, as below+ auto beatAt = [&](double off) { return (blockStart + off - clipStartS) / spb; };+ for (const auto& cp : clip.controllers) {+ if (!cp || cp->points.empty()) continue;+ const ControllerCurve& c = *cp;+ const int32_t dim = kCtlDimBase + c.ctl;+ const double firstBeat = c.points.front().beat;+ // Before a curve's first point it has no say: the controller keeps what it had.+ if (entry && beatAt(first) >= firstBeat - 1e-9 && n < cap) out[n++] = ExprEv{ first, -1, dim, c.valueAt(beatAt(first)) };+ // Recorded points sit on block starts (the capture is block-timed): place each on a whole+ // sample, with a hair of slack, so rounding never lets one fall between two blocks.+ for (const auto& p : c.points) {+ if (n >= cap) break;+ const double rel = clipStartS + p.beat * spb - blockStart;+ const int64_t off = static_cast<int64_t>(std::floor(rel + 1e-6));+ if (off < first || off >= end || off >= frames) continue;+ out[n++] = ExprEv{ static_cast<int32_t>(off), -1, dim, p.value };+ }+ if (!ctlIsSwitch(c.ctl) && c.movesIn(beatAt(first), beatAt(end)))+ for (int32_t off = (first / kStep + 1) * kStep; off < end && n < cap; off += kStep)+ if (beatAt(off) >= firstBeat) out[n++] = ExprEv{ off, -1, dim, c.valueAt(beatAt(off)) };+ }+}++void Engine::clipCtlEndResets(const MidiClip& clip, double clipStartS, double clipEndS, double blockStart,+ int32_t frames, ExprEv* out, int& n, int cap) {+ if (clip.controllers.empty() || clipEndS <= clipStartS || clipEndS < blockStart || clipEndS >= blockStart + frames) return;+ const double lenBeats = clip.lengthBeats;+ const int32_t off = static_cast<int32_t>(clipEndS - blockStart);+ for (const auto& cp : clip.controllers) {+ if (!cp || cp->points.empty() || n >= cap) continue;+ if (!ctlIsSwitch(cp->ctl) && cp->ctl != kCtlPitchWheel) continue;+ if (cp->points.front().beat > lenBeats || cp->valueAt(lenBeats) == kCtlRest) continue;+ out[n++] = ExprEv{ off, -1, kCtlDimBase + cp->ctl, kCtlRest };+ }+}+// Runs the block's sorted note events through the track's MIDI FX chain (bypass =// passthrough). Ping-pongs between evs and scratch (both size >= 1024); the final// list is left in evs. beatStart is the block's beat position for the active clock.@@ -256,12 +327,14 @@ void Engine::poll() {while (recorded_.pop(rn)) batch.push_back(rn);// Expression after the notes: a note's points were all queued before its note-off was.collectRecordedExpr();+ { RecordedCtl x; while (recordedCtl_.pop(x)) ctlBatch_.push_back(x); } // controllers (specs/020)+ const bool ctlWork = !ctlBatch_.empty() || ctlStopPending_;const bool replacePending = replaceUpTo > appliedReplaceUpTo_ && recordSessionScene_ < 0;- if (batch.empty() && !replacePending) return;+ if (batch.empty() && !replacePending && !ctlWork) return;// Session-slot recording (M5-4): notes are already loop-local; append into the slot.if (recordSessionScene_ >= 0 && recordSessionTrackId_ > 0) {- if (batch.empty()) return;+ if (batch.empty() && !ctlWork) return;auto st = findTrackAuthoring(recordSessionTrackId_);if (!st || recordSessionScene_ >= static_cast<int32_t>(st->sessionSlots.size())) return;auto nt = cloneTrack(*st);@@ -275,13 +348,14 @@ void Engine::poll() {attachRecordedExpr(n, r.pitch, r.startBeat);s.midi.notes.push_back(n);}+ foldRecordedCtl(s.midi, L);republishWithTrackRaw(recordSessionTrackId_, nt); // grows the live take, not a new undo stepreturn;}- if (recordTrackId_ <= 0 || recordClipIndex_ < 0) return;+ if (recordTrackId_ <= 0 || recordClipIndex_ < 0) { ctlBatch_.clear(); ctlStopPending_ = false; return; }auto t = findTrackAuthoring(recordTrackId_);- if (!t || recordClipIndex_ >= static_cast<int32_t>(t->midiClips.size())) return;+ if (!t || recordClipIndex_ >= static_cast<int32_t>(t->midiClips.size())) { ctlBatch_.clear(); ctlStopPending_ = false; return; }auto nt = cloneTrack(*t);MidiClip& clip = nt->midiClips[recordClipIndex_];for (auto& r : batch) {@@ -314,6 +388,7 @@ void Engine::poll() {const double end = n.startBeat + n.lengthBeats;if (end > clip.lengthBeats) clip.lengthBeats = end;}+ foldRecordedCtl(clip, 0.0);// Replace: remove the notes this take recorded on earlier passes — matched by pitch and// absolute start, so notes the clip held before the take (or the user drew) stay.if (replacePending) {@@ -333,6 +408,19 @@ void Engine::poll() {takeNotes_.erase(std::remove_if(takeNotes_.begin(), takeNotes_.end(),[&](const TakeNote& k) { return k.pass < replaceUpTo; }),takeNotes_.end());+ // ...and the controller points those passes recorded (the whole pass is replaced).+ for (const TakeCtl& k : takeCtls_) {+ if (k.pass >= replaceUpTo) continue;+ const ControllerCurve* cur = clip.controller(k.ctl);+ if (!cur) continue;+ std::vector<AutomationPoint> pts;+ const double lb = k.absBeat - clip.startBeat;+ for (const auto& p : cur->points) if (std::fabs(p.beat - lb) > 1e-6) pts.push_back(p);+ clip.setController(k.ctl, std::move(pts));+ }+ takeCtls_.erase(std::remove_if(takeCtls_.begin(), takeCtls_.end(),+ [&](const TakeCtl& k) { return k.pass < replaceUpTo; }),+ takeCtls_.end());appliedReplaceUpTo_ = replaceUpTo;}republishWithTrackRaw(recordTrackId_, nt); // grows the live take, not a new undo step@@ -367,6 +455,192 @@ void Engine::attachRecordedExpr(Note& n, int32_t pitch, double startBeat) {n.exprId = storeNoteExpr(e);}+// --- recorded controllers (specs/020) -------------------------------------------+// The audio thread queues every controller sample of the take (RecordedCtl); each poll folds the+// new ones into the take's clip. A controller a pass moves is replaced over the range it touched+// — from its first point in the pass up to the pass end (the loop end, or the record stop) — so+// two passes of the mod wheel never interleave; the controllers a pass didn't move stay, and so+// do the notes (a pedal-only pass re-records only the pedal). The run since the last poll is+// thinned on its own, anchored on the range's last committed point, so a long take stays a+// handful of points per gesture as it grows.++void Engine::resetCtlFold() {+ for (auto& f : ctlFold_) f = CtlFold{};+ ctlBatch_.clear();+ takeCtls_.clear();+ ctlStopPending_ = false;+ RecordedCtl x;+ while (recordedCtl_.pop(x)) {}+}++bool Engine::foldRecordedCtl(MidiClip& clip, double slotLen) {+ const bool slot = slotLen > 0.0;+ bool changed = false;+ for (const RecordedCtl& x : ctlBatch_) {+ if (x.ctl < 0) { // a loop pass ended: its ranges run to the loop end+ for (int32_t c = 0; c < kCtlCount; ++c) {+ CtlFold& f = ctlFold_[c];+ if (!f.open || f.pass != x.pass) continue;+ commitCtlRun(clip, c, slotLen, true);+ closeCtlRange(clip, c, x.beat - clip.startBeat, slotLen);+ f.open = false;+ changed = true;+ }+ continue;+ }+ if (x.ctl >= kCtlCount || ctlIsReserved(x.ctl)) continue;+ CtlFold& f = ctlFold_[x.ctl];+ // A Session take wraps at the slot's end: the range closes there and a new one opens.+ const bool wrapped = slot && f.open && x.beat < f.lastAbs - slotLen * 0.5;+ if (f.open && (f.pass != x.pass || wrapped)) {+ commitCtlRun(clip, x.ctl, slotLen, true);+ closeCtlRange(clip, x.ctl, slot ? slotLen : f.lastAbs - clip.startBeat, slotLen);+ f.open = false;+ changed = true;+ }+ if (!f.open) { f.open = true; f.pass = x.pass; f.startAbs = x.beat; f.hasCommitted = false; f.before = clip.controllerPtr(x.ctl); }+ f.lastAbs = x.beat;+ f.run.push_back(x);+ }+ ctlBatch_.clear();+ for (int32_t c = 0; c < kCtlCount; ++c)+ if (!ctlFold_[c].run.empty()) { commitCtlRun(clip, c, slotLen, false); changed = true; }+ if (ctlStopPending_) { // the take stopped: the open ranges end at the stop+ ctlStopPending_ = false;+ for (int32_t c = 0; c < kCtlCount; ++c) {+ CtlFold& f = ctlFold_[c];+ if (!f.open) continue;+ commitCtlRun(clip, c, slotLen, true); // the points held back for thinning+ closeCtlRange(clip, c, slot ? std::fmod(std::max(0.0, f.lastAbs), slotLen) : ctlStopAt_ - clip.startBeat, slotLen);+ f.open = false;+ changed = true;+ }+ }+ return changed;+}++void Engine::commitCtlRun(MidiClip& clip, int32_t ctl, double slotLen, bool final) {+ CtlFold& f = ctlFold_[ctl];+ if (f.run.empty()) return;+ const bool slot = slotLen > 0.0;+ // A controller moved before the take's clip (on the count-in) moves its left edge back to+ // it, like a pickup note does; never before 1.1.+ if (!slot) {+ double minAbs = f.run.front().beat;+ for (const auto& x : f.run) minAbs = std::min(minAbs, x.beat);+ if (minAbs < clip.startBeat) {+ const double newStart = std::max(0.0, minAbs);+ const double delta = clip.startBeat - newStart;+ if (delta > 0.0) {+ for (auto& o : clip.notes) o.startBeat += delta;+ clip.shiftControllers(delta);+ clip.lengthBeats += delta;+ clip.startBeat = newStart;+ }+ }+ }+ auto local = [&](double abs) { return slot ? std::fmod(std::max(0.0, abs), slotLen) : abs - clip.startBeat; };++ // The run on the take clock, after the range's last committed point (the thinning anchor).+ std::vector<AutomationPoint> pts;+ if (f.hasCommitted) pts.push_back(f.committed);+ for (const auto& x : f.run) {+ const AutomationPoint p{ x.beat, ctlClamp(ctl, x.value), 0.0f };+ if (!pts.empty() && std::fabs(pts.back().beat - p.beat) < 1e-9) pts.back().value = p.value;+ else pts.push_back(p);+ }+ f.run.clear();+ const double loAbs = f.hasCommitted ? f.committed.beat : f.startAbs;+ const double hiAbs = pts.back().beat;+ std::vector<AutomationPoint> kept = ctlIsSwitch(ctl) ? dedupeSwitch(pts) : thinCtlCurve(pts, ctlThinTolerance(ctl));+ if (f.hasCommitted && !kept.empty() && std::fabs(kept.front().beat - f.committed.beat) < 1e-9) kept.erase(kept.begin());+ // A moving curve keeps its last segment back: the points after the last-but-one kept point+ // wait for the next poll, where the thinning may find them on one longer line.+ // (A long straight or steady stretch is committed at 512 points, so the tail stays small.)+ if (!final && !ctlIsSwitch(ctl) && pts.size() <= 512) {+ const double holdFrom = kept.size() >= 2 ? kept[kept.size() - 2].beat+ : (f.hasCommitted ? f.committed.beat : -std::numeric_limits<double>::infinity());+ if (kept.size() >= 2) kept.pop_back(); else kept.clear();+ for (const auto& p : pts)+ if (p.beat > holdFrom + 1e-12 || (kept.empty() && !f.hasCommitted)) f.run.push_back(RecordedCtl{ ctl, p.beat, p.value, f.pass });+ if (kept.empty()) return; // nothing settled yet; the range keeps growing+ }++ // Replace what the clip held over the range so far, then add the run.+ const double loL = local(loAbs), hiL = local(hiAbs);+ std::vector<AutomationPoint> out;+ if (const ControllerCurve* cur = clip.controller(ctl))+ for (const auto& p : cur->points) {+ const bool inRange = f.hasCommitted ? (p.beat > loL + 1e-9 && p.beat <= hiL + 1e-9)+ : (p.beat >= loL - 1e-9 && p.beat <= hiL + 1e-9);+ if (!inRange) out.push_back(p);+ }+ // The range's first commit steps out of the old curve: its value holds to just before.+ if (!f.hasCommitted && f.before && !f.before->points.empty() && f.before->points.front().beat < loL - kCtlJunction) {+ const double j = loL - kCtlJunction;+ if (!kept.empty() && f.before->valueAt(j) != kept.front().value) out.push_back({ j, f.before->valueAt(j), 0.0f });+ }+ for (const auto& p : kept) {+ out.push_back({ local(p.beat), p.value, 0.0f });+ takeCtls_.push_back({ ctl, p.beat, f.pass });+ }+ if (!kept.empty()) { f.committed = kept.back(); f.hasCommitted = true; }+ clip.setController(ctl, std::move(out));+ // Grow the clip so the controller's last move falls inside it (a pedal released late).+ if (!slot && hiL > clip.lengthBeats) clip.lengthBeats = hiL;+}++void Engine::flushCtlTake() {+ { RecordedCtl x; while (recordedCtl_.pop(x)) ctlBatch_.push_back(x); }+ ctlStopPending_ = true;+ ctlStopAt_ = transport_.uiPositionBeats();+ if (recordSessionScene_ >= 0 && recordSessionTrackId_ > 0) {+ auto st = findTrackAuthoring(recordSessionTrackId_);+ if (st && recordSessionScene_ < static_cast<int32_t>(st->sessionSlots.size())) {+ auto nt = cloneTrack(*st);+ SessionSlot& s = nt->sessionSlots[recordSessionScene_];+ if (foldRecordedCtl(s.midi, s.lengthBeats > 0 ? s.lengthBeats : 4.0))+ republishWithTrackRaw(recordSessionTrackId_, nt);+ }+ } else if (recordTrackId_ > 0 && recordClipIndex_ >= 0) {+ auto t = findTrackAuthoring(recordTrackId_);+ if (t && recordClipIndex_ < static_cast<int32_t>(t->midiClips.size())) {+ auto nt = cloneTrack(*t);+ if (foldRecordedCtl(nt->midiClips[recordClipIndex_], 0.0)) republishWithTrackRaw(recordTrackId_, nt);+ }+ }+ resetCtlFold();+}++// End ctl's range at `atLocal` (clip-local): what the clip held between the range's last point+// and there is replaced too; where the old curve goes on past it, a junction point at `atLocal`+// hands back to it with the value it had there.+void Engine::closeCtlRange(MidiClip& clip, int32_t ctl, double atLocal, double slotLen) {+ CtlFold& f = ctlFold_[ctl];+ const ControllerCurve* cur = clip.controller(ctl);+ if (!cur || !f.hasCommitted) return;+ const double lastL = slotLen > 0.0 ? std::fmod(std::max(0.0, f.committed.beat), slotLen) : f.committed.beat - clip.startBeat;+ if (atLocal <= lastL + 1e-9) return;+ // The value the curve had there before this range replaced anything (rest when it had none).+ const float old = f.before && !f.before->points.empty() ? f.before->valueAt(atLocal) : kCtlRest;+ std::vector<AutomationPoint> out;+ bool after = false, at = false;+ for (const auto& p : cur->points) {+ if (p.beat > lastL + 1e-9 && p.beat < atLocal - 1e-9) continue;+ if (p.beat >= atLocal - 1e-9) after = true;+ if (std::fabs(p.beat - atLocal) < 1e-9) at = true;+ out.push_back(p);+ }+ if (after && !at) {+ // Hold the range's last value up to the junction, then hand back to the old curve.+ if (!ctlIsSwitch(ctl) && atLocal - kCtlJunction > lastL + 1e-9 && old != f.committed.value)+ out.push_back({ atLocal - kCtlJunction, f.committed.value, 0.0f });+ out.push_back({ atLocal, old, 0.0f });+ }+ clip.setController(ctl, std::move(out));+ f.before.reset();+}+// --- audio thread ----------------------------------------------------------void Engine::render(float* out, int32_t numFrames) {@@ -580,6 +854,23 @@ void Engine::drainLiveMidi(double blockStartBeat, bool playing) {pendingVel_[p] = livePressVel_[p];}if (rec && timed && liveExprCount_ > 0) captureLiveExpr(nowBeat, slot ? slotLen : 0.0);++ // Recorded controllers (specs/020): the block's coalesced instrument-wide controllers that+ // reach the take, on the capture clock. A take starts with every controller already away+ // from rest (a pedal held down when Record is pressed), at the record start.+ if (rec && takeStarted) {+ const double seedAt = slot ? nowBeat : blockStartBeat;+ for (int32_t c = 0; c < kCtlCount; ++c) {+ const float v = liveCtl_[c].load(std::memory_order_relaxed);+ if (v != kCtlRest && !ctlIsReserved(c)) recordedCtl_.push(RecordedCtl{ c, seedAt, v, recordPass_ });+ }+ }+ if (rec && timed)+ for (int i = 0; i < liveExprCount_; ++i) {+ const MidiEvent& e = liveExpr_[i];+ if (e.expr < kCtlDimBase || (e.trackId >= 0 && e.trackId != recTrack)) continue;+ recordedCtl_.push(RecordedCtl{ e.expr - kCtlDimBase, nowBeat, e.velocity, recordPass_ });+ }}// Recorded MPE: the block's (coalesced) live expression for a note being recorded becomes a@@ -655,6 +946,13 @@ void Engine::captureRoutedNotes(const MidiEv* evs, int n, double blockStart, douint Engine::gatherInstrumentNotes(Track& t, MidiEv* evs, int n, int32_t frames,double blockStart, double spb, bool playing, ExprEv* xev, int* xn) {if (playing) {+ // Controllers first: a clip ending here releases its pedal ahead of the next clip's+ // values at the same offset (the render keeps their order).+ if (xev)+ for (const MidiClip& clip : t.midiClips)+ if (clip.active)+ clipCtlEndResets(clip, clip.startBeat * spb, (clip.startBeat + clip.lengthBeats) * spb,+ blockStart, frames, xev, *xn, kMaxBlockExpr);for (const MidiClip& clip : t.midiClips) {// Deactivated clip (key 0): emit NO new note-ons, but still emit note-offs — so a// note already sounding when the clip was switched off releases instead of hanging.@@ -692,6 +990,8 @@ int Engine::gatherInstrumentNotes(Track& t, MidiEv* evs, int n, int32_t frames,noteExprEvents(note, clipStart + note.startBeat * spb - blockStart, offS - blockStart,frames, spb, xev, *xn, kMaxBlockExpr); // curve timed from the true start}+ // The clip's controllers (specs/020).+ if (xev && clipActive) clipCtlEvents(clip, clipStart, clipEnd, blockStart, frames, spb, chaseNotes_, xev, *xn, kMaxBlockExpr);}}// Notes a loop record replace removed from this track's take: release them (once), unless@@ -728,7 +1028,7 @@ void Engine::applyLiveExpression(Graph* g, const Track& t, Instrument& inst) confor (int i = 0; i < liveExprCount_; ++i) {const MidiEvent& e = liveExpr_[i];if (takesLiveEvent(t, e) || (src && takesLiveEvent(*src, e)))- inst.noteExpression(e.pitch, e.expr, e.velocity);+ deliverExpr(inst, e.pitch, e.expr, e.velocity);}}@@ -854,7 +1154,17 @@ void Engine::renderInstrumentRaw(Graph* g, Track& t, float* dst, int32_t frames,if (j < blockExprN_.size())for (int k = 0; k < blockExprN_[j] && xn < kMaxBlockExpr; ++k) xev[xn++] = blockExpr_[j][k];if (routed && t.armed()) trackRoutedDown(t.id(), srcEvs, m, blockStart, spb, playing || countInActive_);- if (routed && captureRouted) captureRoutedNotes(srcEvs, m, blockStart, spb, countInClockOffset());+ if (routed && captureRouted) {+ captureRoutedNotes(srcEvs, m, blockStart, spb, countInClockOffset());+ // The source's controllers (its clips' curves) print into the take too.+ if (j < blockExprN_.size())+ for (int k = 0; k < blockExprN_[j]; ++k) {+ const ExprEv& x = blockExpr_[j][k];+ if (x.dim < kCtlDimBase) continue;+ recordedCtl_.push(RecordedCtl{ x.dim - kCtlDimBase, (blockStart + x.off) / spb + countInClockOffset(),+ x.value, recordPass_ });+ }+ }}} else {n = computeInstrumentMidi(t, evs, frames, blockStart, spb, playing,@@ -926,6 +1236,20 @@ void Engine::renderSessionSlotRaw(Track& t, float* dst, int32_t frames, double snoteExprEvents(note, (onAbs - p) * spb, (onAbs + note.lengthBeats - p) * spb, frames, spb, xev, xn, kMaxBlockExpr);}}+ // The slot clip's controllers, per loop iteration: a release at each iteration's end, then+ // its values from the start of the next (specs/020).+ if (!s.midi.controllers.empty())+ for (long it = std::max(0L, i0 - 1); it <= i0 + 1; ++it) {+ if (!s.loop && it > 0) break;+ const double cs = (it * L - p) * spb, ce = ((it + 1) * L - p) * spb;+ clipCtlEndResets(s.midi, cs, ce, 0.0, frames, xev, xn, kMaxBlockExpr);+ }+ if (!s.midi.controllers.empty())+ for (long it = std::max(0L, i0 - 1); it <= i0 + 1; ++it) {+ if (!s.loop && it > 0) break;+ const double cs = (it * L - p) * spb, ce = ((it + 1) * L - p) * spb;+ clipCtlEvents(s.midi, cs, ce, 0.0, frames, spb, false, xev, xn, kMaxBlockExpr);+ }std::stable_sort(xev, xev + xn, [](const ExprEv& a, const ExprEv& b) { return a.off < b.off; });// Live monitoring while overdub-recording into this slot (M5-4).@@ -950,7 +1274,7 @@ void Engine::renderSessionSlotRaw(Track& t, float* dst, int32_t frames, double sif (!monitoring) return;for (int i = 0; i < liveExprCount_; ++i)if (liveExpr_[i].trackId < 0 || liveExpr_[i].trackId == t.id())- inst->noteExpression(liveExpr_[i].pitch, liveExpr_[i].expr, liveExpr_[i].velocity);+ deliverExpr(*inst, liveExpr_[i].pitch, liveExpr_[i].expr, liveExpr_[i].velocity);});sp.localBeats = p + db;}@@ -1140,6 +1464,8 @@ void Engine::onLoopWrap(Graph* g, double loopStartBeat, double loopEndBeat) {};for (int p = 0; p < 128; ++p) if (pendingActive_[p]) split(p, pendingStart_[p], pendingVel_[p]);for (int p = 0; p < 128; ++p) if (recRoutedActive_[p]) split(p, recRoutedStart_[p], recRoutedVel_[p]);+ // Controllers being replaced over a range stop at the pass end (specs/020).+ recordedCtl_.push(RecordedCtl{ -1, loopEndBeat, 0.0f, recordPass_ });// A new pass of the take: the continuations above belong to it (they don't trigger a// replace — only a fresh note does), and it takes the loop record mode set right now.++recordPass_;@@ -1172,6 +1498,7 @@ void Engine::processBlock(float* out, int32_t numFrames) {if (g) for (auto& tptr : g->tracks)if (tptr->instrument && !sessionActiveOf(*tptr)) {tptr->instrument->allNotesOff();+ releaseHeldControllers(*tptr->instrument); // a clip's pedal / wheel (specs/020)for (auto& md : tptr->midiEffects) if (md) md->reset(); // flush arp held/pending}};diff --git a/src/native/nota.engine/src/Engine_Session.cpp b/src/native/nota.engine/src/Engine_Session.cppindex c05d789c..7f8eefa2 100644--- a/src/native/nota.engine/src/Engine_Session.cpp+++ b/src/native/nota.engine/src/Engine_Session.cpp@@ -306,6 +306,7 @@ void Engine::recordSessionSlot(int32_t trackId, int32_t scene) {t = findTrackAuthoring(trackId); if (!t) return;}+ resetCtlFold();recordSessionTrackId_ = trackId;recordSessionScene_ = scene;recordSlotLen_.store(t->sessionSlots[scene].lengthBeats, std::memory_order_relaxed);@@ -327,6 +328,8 @@ void Engine::finalizeSessionRecord(bool relaunch) {stopAudioRecording();if (relaunch && tid > 0 && sc >= 0) launchSlot(tid, sc);}+ // The take's last controller points (held back for thinning) go in before the target does.+ if (recordSessionScene_ >= 0 && !recordSessionAudio_) flushCtlTake();// A fresh MIDI take that ran open-ended: cut it to whole launch quanta (a bar when// launching is unquantized) — no undo step of its own, so undo drops the whole take.if (recordSessionGrowing_ && recordSessionScene_ >= 0) {diff --git a/src/native/nota.engine/src/Engine_Tracks.cpp b/src/native/nota.engine/src/Engine_Tracks.cppindex 9e6dd718..86ed5485 100644--- a/src/native/nota.engine/src/Engine_Tracks.cpp+++ b/src/native/nota.engine/src/Engine_Tracks.cpp@@ -1163,11 +1163,13 @@ double placeAudioNonOverlap(const Track& t, double start, double len, double spbMidiClip midiCarveLeft(const MidiClip& src, double endLocal) { // keep [start, start+endLocal)MidiClip r; r.name = src.name; r.startBeat = src.startBeat; r.lengthBeats = endLocal;for (const auto& n : src.notes) if (n.startBeat < endLocal) r.notes.push_back(n);+ r.sliceControllersFrom(src, 0.0, endLocal);return r;}MidiClip midiCarveRight(const MidiClip& src, double startLocal) { // keep [start+startLocal, end)MidiClip r; r.name = src.name; r.startBeat = src.startBeat + startLocal; r.lengthBeats = src.lengthBeats - startLocal;for (const auto& n : src.notes) if (n.startBeat >= startLocal) { Note m = n; m.startBeat -= startLocal; r.notes.push_back(m); }+ r.sliceControllersFrom(src, startLocal, r.lengthBeats);return r;}// Both carves work in PLAYED time, so a reversed clip mirrors: its audible head is the@@ -1817,6 +1819,27 @@ MidiClip consolidateMidiClips(const std::vector<MidiClip>& clips, double s, doub}}out.volumeEnvelope = stitchEnvelopes(spans, s, e);+ // Controllers (specs/020): each clip's piece in turn; where a clip ends holding a pedal down+ // or the wheel bent, it goes back to rest there, as playback releases it.+ std::vector<int32_t> ctls;+ for (const MidiClip* c : src) for (const auto& cv : c->controllers) if (cv && std::find(ctls.begin(), ctls.end(), cv->ctl) == ctls.end()) ctls.push_back(cv->ctl);+ for (int32_t ctl : ctls) {+ std::vector<AutomationPoint> pts;+ for (const MidiClip* c : src) {+ if (!c->active) continue;+ const ControllerCurve* cv = c->controller(ctl);+ if (!cv) continue;+ const double cs = c->startBeat, a = std::max(cs, s), b = std::min(cs + c->lengthBeats, e);+ if (b <= a) continue;+ for (auto p : sliceCtlPoints(*cv, a - cs, b - cs)) { p.beat += a - s; pts.push_back(p); }+ if ((ctlIsSwitch(ctl) || ctl == kCtlPitchWheel) && cv->valueAt(b - cs) != kCtlRest && !cv->points.empty()+ && b - cs >= cv->points.front().beat)+ pts.push_back({ b - s, kCtlRest, 0.0f });+ }+ // A point the next clip pins on the same beat wins (setController keeps the last).+ std::stable_sort(pts.begin(), pts.end(), [](const AutomationPoint& x, const AutomationPoint& y) { return x.beat < y.beat; });+ if (!pts.empty()) out.setController(ctl, std::move(pts));+ }return out;}} // namespace@@ -1912,6 +1935,7 @@ bool Engine::trimClip(int32_t trackId, int32_t clipIndex, double newStartBeat, dMidiClip& c = nt->midiClips[clipIndex];const double delta = newStartBeat - c.startBeat; // shift notes to stay putfor (auto& n : c.notes) n.startBeat -= delta;+ c.shiftControllers(-delta); // and controllers (a point left of the new start still sets the value there)c.startBeat = newStartBeat;c.lengthBeats = newLengthBeats;} else {@@ -2062,6 +2086,8 @@ int32_t Engine::splitClip(int32_t trackId, int32_t clipIndex, double atBeat) {if (n.startBeat < local) left.notes.push_back(n);else { Note m = n; m.startBeat -= local; right.notes.push_back(m); }}+ left.sliceControllersFrom(src, 0.0, local);+ right.sliceControllersFrom(src, local, right.lengthBeats);nt->midiClips[clipIndex] = left;nt->midiClips.insert(nt->midiClips.begin() + clipIndex + 1, right);} else {diff --git a/src/native/nota.engine/src/Instrument.h b/src/native/nota.engine/src/Instrument.hindex ed8b3d61..5721111a 100644--- a/src/native/nota.engine/src/Instrument.h+++ b/src/native/nota.engine/src/Instrument.h@@ -8,11 +8,15 @@#pragma once+#include <atomic>#include <cstdint>+#include <limits>#include <memory>#include <string>#include <vector>+#include "MidiController.h"+#include "NoteExpression.h"#include "TransportInfo.h"namespace nota {@@ -39,6 +43,28 @@ public:// True when noteExpression does something — the UI shows the MPE badge for it.virtual bool supportsMpe() const { return false; }+ // An instrument-wide MIDI controller (specs/020, MidiController.h): ctl 0..127 a CC,+ // kCtlPitchWheel, kCtlChannelPressure; value normalised (CC 0..1, wheel −1..+1). Applied+ // like expression, at segment boundaries. Default: the controllers every built-in already+ // understands go to the instrument-wide expression (wheel, pressure, CC74 slide, CC64+ // sustain — which instruments read as down at >= 0.5); the rest are ignored. A hosted+ // plug-in overrides this to receive every controller as the MIDI message itself.+ // The last value the engine delivered per controller (NaN = none since creation), kept on+ // the instrument because it outlives graph snapshots. Audio thread only: the stop reset+ // and "send on change" read it.+ // Relaxed atomics so a test / meter can read them from the message thread.+ std::atomic<float> deliveredCtl[kCtlCount];+ Instrument() { for (auto& v : deliveredCtl) v.store(std::numeric_limits<float>::quiet_NaN(), std::memory_order_relaxed); }+ virtual void controller(int32_t ctl, float value) {+ switch (ctl) {+ case kCtlPitchWheel: noteExpression(-1, ExprBend, value); break;+ case kCtlChannelPressure: noteExpression(-1, ExprPressure, value); break;+ case 74: noteExpression(-1, ExprSlide, value); break;+ case kCtlSustain: noteExpression(-1, ExprSustain, value); break;+ default: break;+ }+ }+// Add `frames` of interleaved stereo into `out`. Continues current voices.virtual void render(float* out, int32_t frames) = 0;diff --git a/src/native/nota.engine/src/MidiClip.h b/src/native/nota.engine/src/MidiClip.hindex b950ce32..1b409bba 100644--- a/src/native/nota.engine/src/MidiClip.h+++ b/src/native/nota.engine/src/MidiClip.h@@ -8,6 +8,7 @@#pragma once#include "Automation.h"+#include "MidiController.h"#include "NoteExpression.h"#include <algorithm>#include <cmath>@@ -86,6 +87,52 @@ struct MidiClip {// sample during the clip. Empty = no envelope (fast path).AutomationLane velocityEnvelope;AutomationLane volumeEnvelope;+ // Instrument-wide controllers (specs/020): at most one curve per ctl, sorted by ctl.+ // Shared, immutable curves — a clip copy shares them; an edit swaps in a new one.+ std::vector<std::shared_ptr<const ControllerCurve>> controllers;++ const ControllerCurve* controller(int32_t ctl) const {+ for (const auto& c : controllers) if (c && c->ctl == ctl) return c.get();+ return nullptr;+ }+ std::shared_ptr<const ControllerCurve> controllerPtr(int32_t ctl) const {+ for (const auto& c : controllers) if (c && c->ctl == ctl) return c;+ return nullptr;+ }+ // Replace ctl's curve with `pts` (normalised here); empty removes it.+ void setController(int32_t ctl, std::vector<AutomationPoint> pts) {+ normalizeCtlPoints(pts);+ auto it = std::find_if(controllers.begin(), controllers.end(), [&](const auto& c) { return c && c->ctl == ctl; });+ if (pts.empty()) { if (it != controllers.end()) controllers.erase(it); return; }+ auto c = std::make_shared<ControllerCurve>();+ c->ctl = ctl;+ c->points = std::move(pts);+ if (it != controllers.end()) { *it = std::move(c); return; }+ auto at = std::find_if(controllers.begin(), controllers.end(), [&](const auto& x) { return x && x->ctl > ctl; });+ controllers.insert(at, std::move(c));+ }+ // This clip as a piece of `src` starting `from` beats into it, `len` long: its controllers+ // cut to the piece (the first piece keeps a pickup's points before 0).+ void sliceControllersFrom(const MidiClip& src, double from, double len) {+ controllers.clear();+ for (const auto& c : src.controllers) {+ if (!c) continue;+ std::vector<AutomationPoint> p;+ if (from <= 0.0) { for (const auto& x : c->points) if (x.beat < len) p.push_back(x); }+ else p = sliceCtlPoints(*c, from, from + len);+ if (!p.empty()) setController(c->ctl, std::move(p));+ }+ }+ // Shift every controller point by `delta` beats (the clip's left edge moved, notes with it).+ void shiftControllers(double delta) {+ if (delta == 0.0) return;+ for (auto& c : controllers) {+ if (!c) continue;+ auto n = std::make_shared<ControllerCurve>(*c);+ for (auto& p : n->points) p.beat += delta;+ c = std::move(n);+ }+ }};} // namespace notadiff --git a/src/native/nota.engine/src/MidiController.h b/src/native/nota.engine/src/MidiController.hnew file mode 100644index 00000000..024e0376--- /dev/null+++ b/src/native/nota.engine/src/MidiController.h@@ -0,0 +1,143 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.+//+// Instrument-wide MIDI controllers (specs/020): the sustain pedal, mod wheel, any CC, the+// pitch wheel and channel pressure, addressed by one id (`ctl`, NOTA_CTL_* in nota_engine.h):+// 0..127 the CC, 128 the pitch wheel, 129 channel pressure. Values are normalised — a CC+// 0..1 (data / 127), the wheel −1..+1, pressure 0..1.+//+// A MIDI clip keeps one breakpoint curve per controller it uses (ControllerCurve), recorded+// with the notes or drawn in the piano roll. Curves are immutable once built and shared by+// pointer, so cloning a track (every recording poll, every undo checkpoint) copies none of+// their points. Switch controllers (CC64–69: sustain, portamento, sostenuto, soft, legato,+// hold 2) hold their value until the next point; the rest are linear between points.+//+// Inside the engine a controller travels on the expression wire (ExprEv / MidiEvent) with+// pitch −1 and dim kCtlDimBase + ctl, and reaches the instrument through+// Instrument::controller.++#pragma once++#include "Automation.h"+#include <algorithm>+#include <cmath>+#include <cstdint>+#include <memory>+#include <vector>++namespace nota {++inline constexpr int32_t kCtlPitchWheel = 128;+inline constexpr int32_t kCtlChannelPressure = 129;+inline constexpr int32_t kCtlCount = 130;+inline constexpr int32_t kCtlSustain = 64;+inline constexpr int32_t kCtlModWheel = 1;+// Controllers ride the expression wire above every per-note / instrument-wide dim.+inline constexpr int32_t kCtlDimBase = 16;++// Data entry / RPN / NRPN (their meaning comes from the messages around them) and the channel+// mode messages: never recorded, drawn or automated.+inline bool ctlIsReserved(int32_t ctl) {+ if (ctl < 0 || ctl >= kCtlCount) return true;+ return ctl == 6 || ctl == 38 || (ctl >= 96 && ctl <= 101) || (ctl >= 120 && ctl <= 127);+}+inline bool ctlIsSwitch(int32_t ctl) { return ctl >= 64 && ctl <= 69; }+inline float ctlMin(int32_t ctl) { return ctl == kCtlPitchWheel ? -1.0f : 0.0f; }+inline float ctlClamp(int32_t ctl, float v) { return std::clamp(v, ctlMin(ctl), 1.0f); }+// Where a controller rests: pedal up, wheel centred, nothing pressed.+inline constexpr float kCtlRest = 0.0f;++struct ControllerCurve {+ int32_t ctl = kCtlSustain;+ std::vector<AutomationPoint> points; // sorted by beat (clip-local, may be < 0), one per beat++ // Held before the first and after the last point; a switch takes the last point at or+ // before `beat`, the rest interpolate with the automation curve shaping.+ float valueAt(double beat) const {+ const auto& p = points;+ if (p.empty()) return kCtlRest;+ if (beat <= p.front().beat) return p.front().value;+ if (beat >= p.back().beat) return p.back().value;+ auto it = std::upper_bound(p.begin(), p.end(), beat, [](double b, const AutomationPoint& a) { return b < a.beat; });+ const AutomationPoint& b = *it; const AutomationPoint& a = *(it - 1);+ if (ctlIsSwitch(ctl)) return a.value;+ const double span = b.beat - a.beat;+ if (span <= 0.0) return b.value;+ return static_cast<float>(a.value + (b.value - a.value) * AutomationLane::shape((beat - a.beat) / span, a.curve));+ }+ // Whether the curve moves anywhere in [b0, b1) (a linear stretch between differing points).+ bool movesIn(double b0, double b1) const {+ if (ctlIsSwitch(ctl) || points.size() < 2) return false;+ for (size_t i = 1; i < points.size(); ++i)+ if (points[i].beat > b0 && points[i - 1].beat < b1 && points[i].value != points[i - 1].value) return true;+ return false;+ }+};++// Sort by beat and keep the last point given for any one beat.+inline void normalizeCtlPoints(std::vector<AutomationPoint>& p) {+ std::stable_sort(p.begin(), p.end(), [](const AutomationPoint& a, const AutomationPoint& b) { return a.beat < b.beat; });+ std::vector<AutomationPoint> out;+ out.reserve(p.size());+ for (const auto& x : p) {+ if (!std::isfinite(x.beat) || !std::isfinite(x.value)) continue;+ if (!out.empty() && std::fabs(out.back().beat - x.beat) < 1e-9) out.back() = x;+ else out.push_back(x);+ }+ p.swap(out);+}++// A switch keeps only its changes.+inline std::vector<AutomationPoint> dedupeSwitch(const std::vector<AutomationPoint>& p) {+ std::vector<AutomationPoint> out;+ for (const auto& x : p) if (out.empty() || out.back().value != x.value) out.push_back(x);+ return out;+}++// Ramer–Douglas–Peucker over breakpoints (first and last always kept): the fewest points that+// stay within `tol` of a block-rate recording — the shape the gesture had.+inline std::vector<AutomationPoint> thinCtlCurve(const std::vector<AutomationPoint>& p, float tol) {+ if (p.size() <= 2) return p;+ std::vector<char> keep(p.size(), 0);+ keep.front() = keep.back() = 1;+ std::vector<std::pair<size_t, size_t>> stack{ { 0, p.size() - 1 } };+ while (!stack.empty()) {+ auto [a, b] = stack.back(); stack.pop_back();+ if (b <= a + 1) continue;+ float worst = -1.0f; size_t at = a;+ for (size_t i = a + 1; i < b; ++i) {+ const double span = p[b].beat - p[a].beat;+ const double t = span > 0.0 ? (p[i].beat - p[a].beat) / span : 0.0;+ const float d = std::fabs(p[i].value - static_cast<float>(p[a].value + (p[b].value - p[a].value) * t));+ if (d > worst) { worst = d; at = i; }+ }+ if (worst > tol) { keep[at] = 1; stack.push_back({ a, at }); stack.push_back({ at, b }); }+ }+ std::vector<AutomationPoint> out;+ for (size_t i = 0; i < p.size(); ++i) if (keep[i]) out.push_back(p[i]);+ return out;+}++// Recording tolerances: about one 7-bit step for a CC, ~1% of the wheel's travel — the capture+// is block-timed, so a finer tolerance would only keep the block grid's jitter.+inline float ctlThinTolerance(int32_t ctl) { return ctl == kCtlPitchWheel ? 0.012f : 0.008f; }+// A replaced range meets the curve around it in a step: the old value holds up to a hair before+// the range (and the range's last value up to a hair before the old curve takes over again).+inline constexpr double kCtlJunction = 1.0 / 1024.0; // beats++// The curve cut to [from, to) and shifted by -from, with the value at each edge pinned so the+// piece sounds the same (split / slice / slot hand-off). Before the curve's first point nothing+// is pinned: there the controller keeps what it had.+inline std::vector<AutomationPoint> sliceCtlPoints(const ControllerCurve& c, double from, double to) {+ std::vector<AutomationPoint> out;+ if (!c.points.empty() && from >= c.points.front().beat) out.push_back({ 0.0, c.valueAt(from), 0.0f });+ for (const auto& p : c.points)+ if (p.beat > from && p.beat < to) out.push_back({ p.beat - from, p.value, p.curve });+ if (to > from && !ctlIsSwitch(c.ctl) && c.movesIn(from, to)) out.push_back({ to - from, c.valueAt(to), 0.0f });+ if (out.size() > 1 && ctlIsSwitch(c.ctl)) out = dedupeSwitch(out);+ // A piece that never leaves rest carries nothing.+ for (const auto& p : out) if (p.value != kCtlRest) return out;+ return {};+}++} // namespace notadiff --git a/src/native/nota.engine/src/Monolith.h b/src/native/nota.engine/src/Monolith.hindex 197368f4..23ed287f 100644--- a/src/native/nota.engine/src/Monolith.h+++ b/src/native/nota.engine/src/Monolith.h@@ -85,6 +85,11 @@ public:int32_t kind() const override { return 13; }const char* displayName() const override { return "Nota Monolith"; }+ // The mod wheel (CC1) moves the Mod Wheel control, as a learned knob would (specs/020).+ void controller(int32_t ctl, float value) override {+ if (ctl == kCtlModWheel) pn_[ModWheel].store(std::clamp(value, 0.0f, 1.0f), std::memory_order_relaxed);+ Instrument::controller(ctl, value);+ }void setSampleRate(double sr) override { sampleRate_ = sr > 0 ? sr : 44100.0; }int32_t activeVoiceCount() const override { return active_.load(std::memory_order_relaxed); }int32_t heldNotes(int32_t* out, int32_t maxN) const override {diff --git a/src/native/nota.engine/src/MpeInput.h b/src/native/nota.engine/src/MpeInput.hindex edb741e0..4bc642b2 100644--- a/src/native/nota.engine/src/MpeInput.h+++ b/src/native/nota.engine/src/MpeInput.h@@ -26,6 +26,7 @@#include <bit>#include <cstdint>+#include "MidiController.h"#include "NoteExpression.h"namespace nota {@@ -37,6 +38,9 @@ public:virtual void mpeNoteOn(int32_t pitch, float velocity) = 0;virtual void mpeNoteOff(int32_t pitch) = 0;virtual void mpeExpression(int32_t pitch, int32_t dim, float value) = 0; // pitch −1 = all+ // An instrument-wide controller (MidiController.h): the wheel, channel pressure and+ // every CC of an ordinary / master channel, the sustain pedal of any channel.+ virtual void mpeController(int32_t ctl, float value) = 0;};// enabled = treat channels per MPE zones; bendRange = the member channels' default@@ -81,13 +85,13 @@ public:const int32_t raw = (d2 << 7) | d1; // 0..16383, 8192 = centrec.bend = std::clamp((raw - 8192) / 8191.0f, -1.0f, 1.0f);if (member) forHeld(c, [&](int32_t p) { out.mpeExpression(p, ExprBend, c.bend * c.range); });- else out.mpeExpression(-1, ExprBend, c.bend);+ else out.mpeController(kCtlPitchWheel, c.bend);break;}case 0xD0:c.pressure = d1 / 127.0f;if (member) forHeld(c, [&](int32_t p) { out.mpeExpression(p, ExprPressure, c.pressure); });- else out.mpeExpression(-1, ExprPressure, c.pressure);+ else out.mpeController(kCtlChannelPressure, c.pressure);break;case 0xA0:out.mpeExpression(d1, ExprPressure, d2 / 127.0f);@@ -133,15 +137,18 @@ private:case 74:c.slide = v / 127.0f;if (isMember(channel)) forHeld(c, [&](int32_t p) { out.mpeExpression(p, ExprSlide, c.slide); });- else out.mpeExpression(-1, ExprSlide, c.slide);+ else out.mpeController(74, c.slide);break;- case 64: // sustain pedal: instrument-wide on any channel (an MPE master or member)- out.mpeExpression(-1, ExprSustain, v >= 64 ? 1.0f : 0.0f);+ case 64: // sustain pedal: instrument-wide on any channel (an MPE master or member);+ // its real value, so a plug-in piano can half-pedal (built-ins: >= 0.5 down)+ out.mpeController(kCtlSustain, v / 127.0f);break;case 101: c.rpnMsb = v; break;case 100: c.rpnLsb = v; break;case 6: dataEntry(channel, v); break;- default: break;+ default: // any other controller of an ordinary / master channel: instrument-wide+ if (!ctlIsReserved(cc) && !isMember(channel)) out.mpeController(cc, v / 127.0f);+ break;}}diff --git a/src/native/nota.engine/src/OperatorSynth.h b/src/native/nota.engine/src/OperatorSynth.hindex 9adf0fd5..961ea6de 100644--- a/src/native/nota.engine/src/OperatorSynth.h+++ b/src/native/nota.engine/src/OperatorSynth.h@@ -91,6 +91,11 @@ public:int32_t kind() const override { return 9; }const char* displayName() const override { return "Nota Operator"; }+ // The mod wheel (CC1) moves the Mod Wheel control, as a learned knob would (specs/020).+ void controller(int32_t ctl, float value) override {+ if (ctl == kCtlModWheel) pn_[ModWheel].store(std::clamp(value, 0.0f, 1.0f), std::memory_order_relaxed);+ Instrument::controller(ctl, value);+ }void setSampleRate(double sr) override {sampleRate_ = sr > 0 ? sr : 44100.0;std::memset(ring_, 0, sizeof(ring_)); specF0_.store(0.0f, std::memory_order_relaxed);diff --git a/src/native/nota.engine/src/Pentad.h b/src/native/nota.engine/src/Pentad.hindex 4913079b..d0885464 100644--- a/src/native/nota.engine/src/Pentad.h+++ b/src/native/nota.engine/src/Pentad.h@@ -284,6 +284,11 @@ public:const char* displayName() const override { return "Nota Pentad"; }// Deferred to the audio thread (render) so a device-rate change can't race a render.+ // The mod wheel (CC1) moves the Mod Wheel control, as a learned knob would (specs/020).+ void controller(int32_t ctl, float value) override {+ if (ctl == kCtlModWheel) pn_[ModWheel].store(std::clamp(value, 0.0f, 1.0f), std::memory_order_relaxed);+ Instrument::controller(ctl, value);+ }void setSampleRate(double sr) override { pendingRate_.store(sr > 0 ? sr : 44100.0, std::memory_order_relaxed); }int32_t activeVoiceCount() const override { return static_cast<int32_t>(tele_[ScActive].load(std::memory_order_relaxed)); }diff --git a/src/native/nota.engine/src/RackInstrument.h b/src/native/nota.engine/src/RackInstrument.hindex 42bc6281..6a35baed 100644--- a/src/native/nota.engine/src/RackInstrument.h+++ b/src/native/nota.engine/src/RackInstrument.h@@ -62,6 +62,12 @@ public:if (!st) return;for (auto& c : st->chains) if (c.instrument) c.instrument->noteExpression(pitch, dim, value);}+ // Controllers too: every chain hears the pedal and the wheels, like live input.+ void controller(int32_t ctl, float value) override {+ RackState* st = live();+ if (!st) return;+ for (auto& c : st->chains) if (c.instrument) c.instrument->controller(ctl, value);+ }bool supportsMpe() const override {RackState* st = live();if (!st) return false;diff --git a/src/native/nota.engine/src/VoltSynth.h b/src/native/nota.engine/src/VoltSynth.hindex 673a58c2..dd5ae940 100644--- a/src/native/nota.engine/src/VoltSynth.h+++ b/src/native/nota.engine/src/VoltSynth.h@@ -120,6 +120,11 @@ public:int32_t kind() const override { return 6; }const char* displayName() const override { return "Nota Volt"; }+ // The mod wheel (CC1) moves the Mod Wheel control, as a learned knob would (specs/020).+ void controller(int32_t ctl, float value) override {+ if (ctl == kCtlModWheel) pn_[ModWheel].store(std::clamp(value, 0.0f, 1.0f), std::memory_order_relaxed);+ Instrument::controller(ctl, value);+ }void setSampleRate(double sr) override { sampleRate_ = sr > 0 ? sr : 44100.0; exprCoef_ = exprSmoothCoef(sampleRate_); }// MPE: bend → pitch (a keyboard's wheel uses the patch's Bend Range), pressure → level +diff --git a/src/native/nota.engine/src/WavetableSynth.h b/src/native/nota.engine/src/WavetableSynth.hindex 2397f7d0..49545eeb 100644--- a/src/native/nota.engine/src/WavetableSynth.h+++ b/src/native/nota.engine/src/WavetableSynth.h@@ -109,6 +109,11 @@ public:int32_t kind() const override { return 5; }const char* displayName() const override { return "Nota Aurora"; }+ // The mod wheel (CC1) moves the Mod Wheel control, as a learned knob would (specs/020).+ void controller(int32_t ctl, float value) override {+ if (ctl == kCtlModWheel) pn_[ModWheel].store(std::clamp(value, 0.0f, 1.0f), std::memory_order_relaxed);+ Instrument::controller(ctl, value);+ }void setSampleRate(double sr) override {sampleRate_ = sr > 0 ? sr : 44100.0;chorusBuf_.assign((size_t)(sampleRate_ * 0.05) + 2, 0.0f); chorusW_ = 0;diff --git a/src/native/nota.engine/src/nota_engine_audio.cpp b/src/native/nota.engine/src/nota_engine_audio.cppindex d8b135d4..27291136 100644--- a/src/native/nota.engine/src/nota_engine_audio.cpp+++ b/src/native/nota.engine/src/nota_engine_audio.cpp@@ -139,6 +139,13 @@ int32_t nota_mpe_selftest(void) {void mpeNoteOn(int32_t p, float v) override { ev.push_back({0, p, -1, v}); }void mpeNoteOff(int32_t p) override { ev.push_back({1, p, -1, 0.0f}); }void mpeExpression(int32_t p, int32_t d, float v) override { ev.push_back({2, p, d, v}); }+ // Controllers read as instrument-wide expression where they have a dim, else dim+ // kCtlDimBase + ctl.+ void mpeController(int32_t c, float v) override {+ const int32_t d = c == nota::kCtlPitchWheel ? 0 : c == nota::kCtlChannelPressure ? 1 : c == 74 ? 2+ : c == nota::kCtlSustain ? 3 : nota::kCtlDimBase + c;+ ev.push_back({2, -1, d, v});+ }bool has(int kind, int32_t p, int32_t d, float v) const {for (const auto& e : ev) if (e.kind == kind && e.pitch == p && e.dim == d && std::fabs(e.v - v) < 0.02f) return true;return false;@@ -180,6 +187,16 @@ int32_t nota_mpe_selftest(void) {{ const int raw = 16383; off.message(0xE0, 1, raw & 0x7F, raw >> 7, r); }off.message(0xA0, 1, 60, 127, r);if (r.ev.size() != 3 || !r.has(2, -1, 0, 1.0f) || !r.has(2, 60, 1, 1.0f)) return 8;+ // 9: every other CC of an ordinary channel is a controller (the mod wheel, expression), the+ // pedal keeps its value, and data entry / channel mode messages are not controllers.+ r.ev.clear();+ off.message(0xB0, 1, 1, 127, r); off.message(0xB0, 1, 11, 64, r); off.message(0xB0, 1, 64, 40, r);+ off.message(0xB0, 1, 123, 0, r); off.message(0xB0, 1, 38, 5, r);+ if (r.ev.size() != 3 || !r.has(2, -1, nota::kCtlDimBase + 1, 1.0f) || !r.has(2, -1, nota::kCtlDimBase + 11, 64 / 127.0f)+ || !r.has(2, -1, 3, 40 / 127.0f)) return 9;+ // 10: a member channel's CC stays out of the instrument-wide controllers (MPE on).+ r.ev.clear(); m.message(0xB0, 1, 1, 100, r);+ if (!r.ev.empty()) return 10;return 0;}diff --git a/src/native/nota.engine/src/nota_engine_core.cpp b/src/native/nota.engine/src/nota_engine_core.cppindex f502c169..f5c1b5a6 100644--- a/src/native/nota.engine/src/nota_engine_core.cpp+++ b/src/native/nota.engine/src/nota_engine_core.cpp@@ -9,6 +9,8 @@#include "nota_engine_internal.h"+#include <cmath>+#include <limits>#include <new>#include <string>@@ -202,6 +204,18 @@ NotaResult nota_track_note_expression(NotaEngine* e, int32_t track_id, int32_t pif (!e || pitch < -1 || pitch > 127 || dim < 0 || dim > 3 || (dim == 3 && pitch >= 0)) return NOTA_ERR_INVALID_ARG;ENG(e)->trackNoteExpression(track_id, pitch, dim, value); return NOTA_OK;}+NotaResult nota_engine_controller(NotaEngine* e, int32_t ctl, float value) {+ if (!e || nota::ctlIsReserved(ctl) || !std::isfinite(value)) return NOTA_ERR_INVALID_ARG;+ ENG(e)->controller(ctl, value); return NOTA_OK;+}+NotaResult nota_track_controller(NotaEngine* e, int32_t track_id, int32_t ctl, float value) {+ if (!e || nota::ctlIsReserved(ctl) || !std::isfinite(value)) return NOTA_ERR_INVALID_ARG;+ ENG(e)->trackController(track_id, ctl, value); return NOTA_OK;+}+float nota_track_delivered_controller(const NotaEngine* e, int32_t track_id, int32_t ctl) {+ return e ? CENG(e)->deliveredController(track_id, ctl) : std::numeric_limits<float>::quiet_NaN();+}+int32_t nota_engine_midi_ctl_selftest(NotaEngine* e) { return e ? ENG(e)->midiCtlSelfTest() : -1; }void nota_engine_set_audition_track(NotaEngine* e, int32_t track_id) {if (e) ENG(e)->setAuditionTrack(track_id);}diff --git a/src/native/nota.engine/src/nota_engine_session.cpp b/src/native/nota.engine/src/nota_engine_session.cppindex 9facda9d..499c414c 100644--- a/src/native/nota.engine/src/nota_engine_session.cpp+++ b/src/native/nota.engine/src/nota_engine_session.cpp@@ -245,4 +245,15 @@ int32_t nota_session_take_scene_tempo(NotaEngine* e, double* bpm, int32_t* num,return (e && ENG(e)->takeSceneTempoChange(bpm, num, den)) ? 1 : 0;}+int32_t nota_session_ctl_list(const NotaEngine* e, int32_t track_id, int32_t scene, int32_t* out_ctls, int32_t cap) {+ return e ? CENG(e)->ctlList(track_id, true, scene, out_ctls, cap) : 0;+}+int32_t nota_session_ctl_get(const NotaEngine* e, int32_t track_id, int32_t scene, int32_t ctl, NotaAutomationPoint* out, int32_t cap) {+ return e ? CENG(e)->ctlGet(track_id, true, scene, ctl, out, cap) : 0;+}+NotaResult nota_session_ctl_set(NotaEngine* e, int32_t track_id, int32_t scene, int32_t ctl, const NotaAutomationPoint* pts, int32_t count) {+ if (!e) return NOTA_ERR_INVALID_ARG;+ return ENG(e)->ctlSet(track_id, true, scene, ctl, pts, count) ? NOTA_OK : NOTA_ERR_INVALID_ARG;+}+} // extern "C"diff --git a/src/native/nota.engine/src/nota_engine_track.cpp b/src/native/nota.engine/src/nota_engine_track.cppindex 01f973cf..6b581c1c 100644--- a/src/native/nota.engine/src/nota_engine_track.cpp+++ b/src/native/nota.engine/src/nota_engine_track.cpp@@ -703,4 +703,15 @@ int32_t nota_track_sampler_info(const NotaEngine* e, int32_t track_id, NotaSamplreturn (e && CENG(e)->samplerInfo(track_id, out)) ? 1 : 0;}+int32_t nota_midi_clip_ctl_list(const NotaEngine* e, int32_t track_id, int32_t clip_index, int32_t* out_ctls, int32_t cap) {+ return e ? CENG(e)->ctlList(track_id, false, clip_index, out_ctls, cap) : 0;+}+int32_t nota_midi_clip_ctl_get(const NotaEngine* e, int32_t track_id, int32_t clip_index, int32_t ctl, NotaAutomationPoint* out, int32_t cap) {+ return e ? CENG(e)->ctlGet(track_id, false, clip_index, ctl, out, cap) : 0;+}+NotaResult nota_midi_clip_ctl_set(NotaEngine* e, int32_t track_id, int32_t clip_index, int32_t ctl, const NotaAutomationPoint* pts, int32_t count) {+ if (!e) return NOTA_ERR_INVALID_ARG;+ return ENG(e)->ctlSet(track_id, false, clip_index, ctl, pts, count) ? NOTA_OK : NOTA_ERR_INVALID_ARG;+}+} // extern "C"diff --git a/tests/Nota.SmokeTest/MidiControllerTests.cs b/tests/Nota.SmokeTest/MidiControllerTests.csnew file mode 100644index 00000000..fb6f2364--- /dev/null+++ b/tests/Nota.SmokeTest/MidiControllerTests.cs@@ -0,0 +1,547 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.+//+// MIDI controllers in clips (specs/020): the sustain pedal, pitch wheel, channel pressure and+// any CC recorded with the notes, played back (with chase and an end-of-clip release), carried+// through clip edits, saved with the project. The instrument side is observed through the+// engine's last-delivered controller value, plus an audible check on Nota Keys' pedal.++using Nota.Application;+using Nota.Infrastructure;++namespace Nota.SmokeTest;++internal static class MidiControllerTests+{+ private const int Block = 512;++ private static float[] Render(NotaEngine e, int blocks)+ {+ var all = new float[blocks * Block];+ var b = new float[Block * 2];+ for (int k = 0; k < blocks; k++)+ {+ e.RenderOffline(b, Block, 48000);+ for (int i = 0; i < Block; i++) all[k * Block + i] = (b[i * 2] + b[i * 2 + 1]) * 0.5f;+ }+ return all;+ }++ private const double Sr = 48000.0;+ private const double Spb = Sr * 60.0 / 120.0; // frames per beat at 120 BPM+ private const int Chunk = 256;+ private const int Sustain = MidiController.Sustain, Mod = MidiController.ModWheel, Wheel = MidiController.PitchWheel;++ public static IEnumerable<(bool, string)> Run()+ {+ foreach (var r in SelfTest()) yield return r;+ foreach (var r in RoundTrip()) yield return r;+ foreach (var r in Recording()) yield return r;+ foreach (var r in Playback()) yield return r;+ foreach (var r in Chase()) yield return r;+ foreach (var r in EndRelease()) yield return r;+ foreach (var r in SplitCarry()) yield return r;+ foreach (var r in OverdubFold()) yield return r;+ foreach (var r in PedalOnlyReplace()) yield return r;+ foreach (var r in Persistence()) yield return r;+ foreach (var r in LongTake()) yield return r;+ foreach (var r in SessionSlot()) yield return r;+ foreach (var r in Routed()) yield return r;+ foreach (var r in CountInPickup()) yield return r;+ foreach (var r in OldProject()) yield return r;+ }++ // Render `beats` of the engine's own clock (whatever it is doing: playing, counting in).+ private static void Beats(NotaEngine e, double beats)+ {+ var b = new float[Chunk * 2];+ for (long f = 0, n = (long)Math.Round(beats * Spb); f < n; f += Chunk) e.RenderOffline(b, Chunk, Sr);+ }++ // An instrument track at 120 BPM, timed on an absolute clock from the last Play / Record.+ private sealed class Rig : IDisposable+ {+ public readonly NotaEngine E = new();+ public readonly int Track;+ private long _frames;++ public Rig(int kind = 0, bool? loopReplace = null)+ {+ E.SetBpm(120);+ E.SetMetronome(false);+ E.SetCountIn(0);+ Track = E.AddInstrumentTrack();+ E.SetTrackBuiltinInstrument(Track, kind);+ if (loopReplace is { } rep) { E.SetLoop(true, 0.0, 4.0); E.SetLoopRecordMode(rep); }+ E.StopTransport();+ E.Seek(0.0);+ E.RenderOffline(new float[Chunk * 2], Chunk, Sr);+ }++ public void Record() { E.SetTrackArmed(Track, true); E.SetRecording(true); _frames = 0; }+ public void Play(double from = 0.0) { E.Seek(from); E.Play(); _frames = (long)Math.Round(from * Spb); }+ public void Stop() { E.Poll(); E.SetRecording(false); E.Poll(); }++ // Render up to an absolute beat.+ public void To(double beat)+ {+ var b = new float[Chunk * 2];+ long target = (long)Math.Round(beat * Spb);+ while (_frames < target) { E.RenderOffline(b, Chunk, Sr); _frames += Chunk; }+ }++ public void Ctl(int ctl, float v, double at) { To(at); E.SendTrackController(Track, ctl, v); }+ public void Note(int pitch, double at, double len = 0.25) { To(at); E.TrackNoteOn(Track, pitch, 0.8f); To(at + len); E.TrackNoteOff(Track, pitch); }+ public float Got(int ctl) => E.DeliveredController(Track, ctl);++ // The take: (clip start, clip index) of the first MIDI clip on the track.+ public (double Start, int Index) Take()+ {+ E.Poll();+ return E.TryGetClipInfo(Track, 0, out var ci) ? (ci.StartBeat, 0) : (0, -1);+ }+ // The value of `ctl` at an absolute beat in the take, read back through the ABI.+ public float At(int ctl, double beat)+ {+ var (start, c) = Take();+ return c < 0 ? float.NaN : ValueAt(E.GetMidiClipController(Track, c, ctl), ctl, beat - start);+ }++ public void Dispose() => E.Dispose();+ }++ // Mirrors the engine's curve read (switch: last point at or before; else linear, no shaping).+ private static float ValueAt(AutomationPoint[] p, int ctl, double beat)+ {+ if (p.Length == 0) return 0f;+ if (beat <= p[0].Beat) return p[0].Value;+ if (beat >= p[^1].Beat) return p[^1].Value;+ int i = 1; while (p[i].Beat < beat) i++;+ if (MidiController.IsSwitch(ctl)) return p[i - 1].Value;+ double t = (beat - p[i - 1].Beat) / (p[i].Beat - p[i - 1].Beat);+ return (float)(p[i - 1].Value + (p[i].Value - p[i - 1].Value) * t);+ }++ private static bool Near(float a, float b, float tol = 0.02f) => Math.Abs(a - b) <= tol;+ private static string Pts(AutomationPoint[] p) => string.Join(" ", p.Select(x => $"{x.Beat:F2}:{x.Value:F2}"));++ private static IEnumerable<(bool, string)> SelfTest()+ {+ using var e = new NotaEngine();+ int st = e.MidiCtlSelfTest();+ yield return (st == 0, $"controller curves: value at a beat, slices, playback wire, recording fold (self-test {st})");+ }++ // Set / get / list / remove, reserved controllers refused, undo restores.+ private static IEnumerable<(bool, string)> RoundTrip()+ {+ using var e = new NotaEngine();+ int t = e.AddInstrumentTrack();+ int c = e.AddMidiClip(t, 0, 4);+ e.SetMidiClipController(t, c, Sustain, new[] { new AutomationPoint(3, 0f), new AutomationPoint(1, 1f) });+ e.SetMidiClipController(t, c, Mod, new[] { new AutomationPoint(0, 0f), new AutomationPoint(2, 0.5f), new AutomationPoint(2, 1f) });+ var list = e.GetMidiClipControllers(t, c);+ var sus = e.GetMidiClipController(t, c, Sustain);+ var mod = e.GetMidiClipController(t, c, Mod);+ yield return (list.SequenceEqual(new[] { Mod, Sustain }) && sus.Length == 2 && sus[0].Beat == 1 && sus[0].Value == 1f+ && mod.Length == 2 && mod[1].Value == 1f,+ $"clip controllers round-trip: sorted by beat, the last point per beat kept, listed ascending ({Pts(sus)} | {Pts(mod)})");++ bool refused = true;+ foreach (int r in new[] { 6, 38, 98, 121, 130 })+ try { e.SetMidiClipController(t, c, r, new[] { new AutomationPoint(0, 1f) }); refused = false; } catch { }+ yield return (refused && e.GetMidiClipControllers(t, c).Length == 2, "data entry, NRPN, channel mode and unknown controllers are refused");++ e.SetMidiClipController(t, c, Mod, Array.Empty<AutomationPoint>());+ bool removed = e.GetMidiClipControllers(t, c).SequenceEqual(new[] { Sustain });+ e.Undo();+ yield return (removed && e.GetMidiClipController(t, c, Mod).Length == 2, "an empty set removes the curve; undo brings it back");+ }++ // Recording: the pedal, a wheel ramp and the mod wheel land in the take, thinned.+ private static IEnumerable<(bool, string)> Recording()+ {+ using (var r = new Rig())+ {+ r.Record();+ r.Ctl(Sustain, 1f, 0.5);+ r.Note(60, 0.6, 0.3);+ for (int k = 0; k <= 40; k++) // the wheel −1 → +1 over beats 1–3; the mod wheel up at 1.5, the pedal up at 2+ {+ r.Ctl(Wheel, -1f + k / 20f, 1.0 + k * 0.05);+ if (k == 10) r.E.SendTrackController(r.Track, Mod, 0.6f);+ if (k == 20) r.E.SendTrackController(r.Track, Sustain, 0f);+ }+ r.To(4.0);+ r.Stop();+ var (start, c) = r.Take();+ var sus = c >= 0 ? r.E.GetMidiClipController(r.Track, c, Sustain) : Array.Empty<AutomationPoint>();+ var wh = c >= 0 ? r.E.GetMidiClipController(r.Track, c, Wheel) : Array.Empty<AutomationPoint>();+ yield return (sus.Length == 2 && Near(r.At(Sustain, 1.0), 1f) && Near(r.At(Sustain, 3.0), 0f)+ && Math.Abs(start + sus[0].Beat - 0.5) < 0.02 && Math.Abs(start + sus[1].Beat - 2.0) < 0.02,+ $"the sustain pedal is recorded where it was pressed and released ({Pts(sus)}, clip at {start:F2})");+ yield return (Near(r.At(Wheel, 1.0), -1f, 0.05f) && Near(r.At(Wheel, 2.0), 0f, 0.06f) && Near(r.At(Wheel, 3.2), 1f, 0.05f) && wh.Length <= 20,+ $"a pitch-wheel ramp is recorded and thinned to its shape (41 moves → {wh.Length} points, {r.At(Wheel, 1.0):F2}/{r.At(Wheel, 2.0):F2}/{r.At(Wheel, 3.2):F2}: {Pts(wh)})");+ yield return (float.IsNaN(r.At(Mod, 1.2)) is false && r.E.GetMidiClipController(r.Track, c, Mod).Length == 1 && Near(r.At(Mod, 2.0), 0.6f)+ && Math.Abs(start + r.E.GetMidiClipController(r.Track, c, Mod)[0].Beat - 1.5) < 0.02,+ $"the mod wheel is recorded where it moved ({Pts(r.E.GetMidiClipController(r.Track, c, Mod))})");+ }++ // A pedal already down when Record is pressed is in the take from its start.+ using (var r = new Rig())+ {+ r.E.SendTrackController(r.Track, Sustain, 1f);+ r.E.RenderOffline(new float[Chunk * 2], Chunk, Sr);+ r.Record();+ r.Note(60, 0.5);+ r.Ctl(Sustain, 0f, 1.5);+ r.To(2.0);+ r.Stop();+ yield return (Near(r.At(Sustain, 0.6), 1f) && Near(r.At(Sustain, 1.8), 0f),+ $"a pedal held when recording starts is recorded from the take's start ({r.At(Sustain, 0.6):F2}/{r.At(Sustain, 1.8):F2})");+ }++ // Disarming the track ends the take: the mod wheel's moving last stretch is still in it.+ using (var r = new Rig())+ {+ r.Record();+ r.Note(60, 0.2);+ for (int k = 0; k <= 20; k++) r.Ctl(Mod, k / 20f, 1.0 + k * 0.1); // 0 → 1 over beats 1–3+ r.To(3.2);+ r.E.SetTrackArmed(r.Track, false);+ r.E.Poll();+ var mod = r.E.GetMidiClipController(r.Track, 0, Mod);+ yield return (mod.Length >= 2 && Near(mod[^1].Value, 1f, 0.03f),+ $"disarming the record track keeps the controllers up to its last move ({Pts(mod)})");+ }++ // Polyphonic aftertouch (an ordinary keyboard) lands in the note's own pressure.+ using (var r = new Rig())+ {+ r.Record();+ r.To(0.5);+ r.E.TrackNoteOn(r.Track, 57, 0.8f);+ for (int k = 1; k <= 10; k++) { r.To(0.5 + k * 0.05); r.E.TrackNoteExpression(r.Track, 57, NoteExpressionDim.Pressure, 0.9f); }+ r.To(1.5);+ r.E.TrackNoteOff(r.Track, 57);+ r.To(2.0);+ r.Stop();+ var n = r.E.GetClipNotes(r.Track, 0).FirstOrDefault(x => x.Pitch == 57);+ var curve = n.ExprId > 0 ? r.E.GetNoteExpression(n.ExprId) : Array.Empty<NotaExprPoint>();+ yield return (curve.Any(p => p.Dim == NoteExpressionDim.Pressure && Math.Abs(p.Value - 0.9f) < 0.01f),+ "polyphonic aftertouch is recorded as the note's pressure");+ }+ }++ // A clip's curves reach the instrument: a step for the pedal, a ramp for the mod wheel.+ private static Rig ClipRig()+ {+ var r = new Rig();+ int c = r.E.AddMidiClip(r.Track, 0, 8);+ r.E.SetClipNotes(r.Track, c, new[] { new NotaNote(60, 0, 8, 0.8f) });+ r.E.SetMidiClipController(r.Track, c, Sustain, new[] { new AutomationPoint(1, 1f), new AutomationPoint(3, 0f) });+ r.E.SetMidiClipController(r.Track, c, Mod, new[] { new AutomationPoint(0, 0f), new AutomationPoint(2, 1f) });+ return r;+ }++ private static IEnumerable<(bool, string)> Playback()+ {+ using var r = ClipRig();+ r.Play();+ r.To(0.5);+ float s0 = r.Got(Sustain), m0 = r.Got(Mod);+ r.To(1.5);+ float s1 = r.Got(Sustain), m1 = r.Got(Mod);+ r.To(3.5);+ float s2 = r.Got(Sustain), m2 = r.Got(Mod);+ yield return (Near(s0, 1f) is false && Near(s1, 1f) && Near(s2, 0f),+ $"clip playback presses and releases the pedal at its beats ({s0:F2} → {s1:F2} → {s2:F2})");+ yield return (Near(m0, 0.25f, 0.04f) && Near(m1, 0.75f, 0.04f) && Near(m2, 1f),+ $"clip playback moves the mod wheel along its curve ({m0:F2} → {m1:F2} → {m2:F2})");+ }++ private static IEnumerable<(bool, string)> Chase()+ {+ using var r = ClipRig();+ r.Play(2.5);+ r.To(2.5 + 0.02);+ yield return (Near(r.Got(Sustain), 1f) && Near(r.Got(Mod), 1f),+ $"starting playback mid-clip first sets each controller to its value there (pedal {r.Got(Sustain):F2}, mod {r.Got(Mod):F2})");+ }++ private static IEnumerable<(bool, string)> EndRelease()+ {+ using (var r = new Rig())+ {+ int c = r.E.AddMidiClip(r.Track, 0, 2);+ r.E.SetClipNotes(r.Track, c, new[] { new NotaNote(60, 0, 2, 0.8f) });+ r.E.SetMidiClipController(r.Track, c, Sustain, new[] { new AutomationPoint(0, 1f) });+ r.E.SetMidiClipController(r.Track, c, Wheel, new[] { new AutomationPoint(0, 0.5f) });+ r.Play();+ r.To(1.0);+ float inside = r.Got(Sustain), wIn = r.Got(Wheel);+ r.To(2.5);+ yield return (Near(inside, 1f) && Near(wIn, 0.5f) && Near(r.Got(Sustain), 0f) && Near(r.Got(Wheel), 0f),+ $"at a clip's end its pedal is released and the wheel centred ({inside:F2}/{wIn:F2} → {r.Got(Sustain):F2}/{r.Got(Wheel):F2})");+ }+ using (var r = ClipRig())+ {+ r.Play();+ r.To(2.0);+ float held = r.Got(Sustain);+ r.E.StopTransport();+ r.E.RenderOffline(new float[Chunk * 2], Chunk, Sr);+ r.E.RenderOffline(new float[Chunk * 2], Chunk, Sr);+ yield return (Near(held, 1f) && Near(r.Got(Sustain), 0f),+ $"stopping the transport releases a pedal the clip held ({held:F2} → {r.Got(Sustain):F2})");+ }+ }++ // Splitting a clip keeps each half sounding the same: the right half starts with the pedal down.+ private static IEnumerable<(bool, string)> SplitCarry()+ {+ using var r = ClipRig();+ int right = r.E.SplitClip(r.Track, 0, 2.0);+ var left = r.E.GetMidiClipController(r.Track, 0, Sustain);+ var rgt = right >= 0 ? r.E.GetMidiClipController(r.Track, right, Sustain) : Array.Empty<AutomationPoint>();+ var rmod = right >= 0 ? r.E.GetMidiClipController(r.Track, right, Mod) : Array.Empty<AutomationPoint>();+ yield return (right >= 0 && Near(ValueAt(left, Sustain, 1.5), 1f) && Near(ValueAt(rgt, Sustain, 0.0), 1f)+ && Near(ValueAt(rgt, Sustain, 1.5), 0f) && Near(ValueAt(rmod, Mod, 0.0), 1f),+ $"a split carries the controllers: each half keeps its part ({Pts(left)} | {Pts(rgt)} | mod {Pts(rmod)})");+ }++ // Overdub: a later pass replaces the mod wheel only where it moved it.+ private static IEnumerable<(bool, string)> OverdubFold()+ {+ using var r = new Rig(loopReplace: false);+ r.Record();+ r.Note(60, 0.1);+ r.Ctl(Mod, 0.3f, 0.2);+ r.Ctl(Mod, 0.3f, 3.6);+ r.Ctl(Mod, 0.9f, 4.0 + 2.0); // pass 1: from beat 2 of the loop on+ r.Ctl(Mod, 0.9f, 4.0 + 3.0);+ r.To(8.2);+ r.Stop();+ var (_, c) = r.Take();+ var mod = c >= 0 ? r.E.GetMidiClipController(r.Track, c, Mod) : Array.Empty<AutomationPoint>();+ yield return (Near(r.At(Mod, 1.0), 0.3f) && Near(r.At(Mod, 3.0), 0.9f) && r.E.GetClipNotes(r.Track, 0).Length == 1,+ $"loop overdub: a pass replaces a controller only over the range it moved it ({Pts(mod)})");+ }++ // Replace: a pass with only the pedal re-records the pedal there and keeps the notes.+ private static IEnumerable<(bool, string)> PedalOnlyReplace()+ {+ using var r = new Rig(loopReplace: true);+ r.Record();+ foreach (var at in new[] { 0.1, 1.1, 2.1, 3.1 }) r.Note(60, at);+ r.Ctl(Sustain, 1f, 0.5);+ r.Ctl(Sustain, 0f, 3.5);+ r.Ctl(Sustain, 1f, 4.0 + 2.0); // pass 1: no notes, a shorter pedal+ r.Ctl(Sustain, 0f, 4.0 + 3.0);+ r.To(8.2);+ r.Stop();+ int notes = r.E.GetClipNotes(r.Track, 0).Length;+ yield return (notes == 4 && Near(r.At(Sustain, 1.0), 1f) && Near(r.At(Sustain, 2.5), 1f) && Near(r.At(Sustain, 3.2), 0f),+ $"loop replace: a pedal-only pass keeps the notes and re-records the pedal where it was pressed (notes {notes}, " ++ $"{r.At(Sustain, 1.0):F0}/{r.At(Sustain, 2.5):F0}/{r.At(Sustain, 3.2):F0})");+ }++ // SC-005: two minutes of continuous wheel and mod-wheel movement over a played part stay a+ // compact take (the project grows by well under 100 KB) and cost the render no more than a+ // little over the same take without them. The UI's ~30 Hz poll folds the take as it grows.+ private static IEnumerable<(bool, string)> LongTake()+ {+ (double meanUs, double maxUs, long projBytes, int points) Take(bool moveControllers)+ {+ using var r = new Rig();+ r.Record();+ var b = new float[Chunk * 2];+ var sw = new System.Diagnostics.Stopwatch();+ double total = 0, worst = 0; long blocks = 0;+ const double Beats = 240.0; // 2 minutes at 120 BPM+ long frames = 0, end = (long)(Beats * Spb);+ int k = 0;+ while (frames < end)+ {+ double beat = frames / Spb;+ if (k % 24 == 0) { int p = 48 + (k / 24) % 24; r.E.TrackNoteOn(r.Track, p, 0.8f); }+ if (k % 24 == 12) { int p = 48 + (k / 24) % 24; r.E.TrackNoteOff(r.Track, p); }+ if (moveControllers)+ {+ r.E.SendTrackController(r.Track, Wheel, (float)Math.Sin(beat * 1.3));+ r.E.SendTrackController(r.Track, Mod, (float)(0.5 + 0.5 * Math.Sin(beat * 0.37)));+ }+ sw.Restart();+ r.E.RenderOffline(b, Chunk, Sr);+ double us = sw.Elapsed.TotalMilliseconds * 1000.0;+ total += us; worst = Math.Max(worst, us); blocks++;+ frames += Chunk; k++;+ if (k % 6 == 0) r.E.Poll(); // ~30 Hz, as the UI polls+ }+ r.Stop();+ int pts = 0;+ foreach (int ctl in r.E.GetMidiClipControllers(r.Track, 0)) pts += r.E.GetMidiClipController(r.Track, 0, ctl).Length;+ string dir = Path.Combine(Path.GetTempPath(), "nota-smoke-ctl-long-" + Guid.NewGuid().ToString("N") + ".nota");+ try+ {+ ProjectService.Save(ProjectService.Capture(r.E, new TransportState(120.0, 1.0, false, false), new List<string>()), dir, r.E);+ long bytes = new FileInfo(Path.Combine(dir, ProjectService.ManifestName)).Length;+ return (total / blocks, worst, bytes, pts);+ }+ finally { try { Directory.Delete(dir, true); } catch { } }+ }++ var plain = Take(false);+ var moved = Take(true);+ long grow = moved.projBytes - plain.projBytes;+ yield return (grow < 100 * 1024 && moved.points > 10,+ $"a 2-minute take with the wheels moving all through stays compact ({moved.points} points, project +{grow / 1024.0:F1} KB)");+ double blockUs = Chunk / Sr * 1e6;+ yield return TimingBudget.Check(true, moved.meanUs < plain.meanUs * 1.25 + 5 && moved.maxUs < blockUs,+ $"…and costs the render about the same (mean {plain.meanUs:F1} → {moved.meanUs:F1} µs, worst {moved.maxUs:F0} µs of a {blockUs:F0} µs block)");+ }++ // A Session slot take: the controllers land loop-local — the moving mod wheel's last stretch+ // included (T062: a slot take ends without a record stop) — and the slot plays them back on+ // every pass.+ private static IEnumerable<(bool, string)> SessionSlot()+ {+ using var r = new Rig();+ var e = r.E;+ e.SetLaunchQuant(0.0);+ e.SetTrackArmed(r.Track, true);+ e.Seek(0);+ Beats(e, 0.01);+ e.RecordSessionSlot(r.Track, 0);+ Beats(e, 0.25);+ // Ordinary live input, as a slot take records it (track-addressed input plays only its track).+ e.SendController(Sustain, 1f);+ for (int k = 0; k <= 30; k++) { e.SendController(Mod, k / 30f); Beats(e, 0.1); } // 0 → 1 over 3 beats+ e.SendController(Sustain, 0f);+ Beats(e, 0.5);+ e.Poll();+ e.StopSessionRecord();+ e.Poll();+ var sus = e.GetSessionController(r.Track, 0, Sustain);+ var mod = e.GetSessionController(r.Track, 0, Mod);+ double len = e.SessionSlotLength(r.Track, 0);+ yield return (sus.Length == 2 && sus[0].Beat >= 0 && sus[^1].Beat < len && Near(ValueAt(sus, Sustain, 1.0), 1f) && Near(ValueAt(sus, Sustain, 3.8), 0f),+ $"a Session slot take records the pedal loop-local ({Pts(sus)}, slot {len:F0} beats)");+ yield return (mod.Length >= 2 && Near(mod[^1].Value, 1f, 0.04f) && mod[^1].Beat > 2.9,+ $"…and the moving mod wheel to its last move, when the slot take ends ({Pts(mod)})");++ // Play the slot: the pedal is down at beat 1 of each pass, up by 3.8.+ e.StopAllSession();+ Beats(e, 0.1);+ e.LaunchSlot(r.Track, 0);+ Beats(e, 1.0);+ float p1 = r.Got(Sustain);+ Beats(e, 2.8);+ float p1up = r.Got(Sustain);+ Beats(e, 0.2 + 1.0); // into the second pass, beat 1+ float p2 = r.Got(Sustain);+ yield return (Near(p1, 1f) && Near(p1up, 0f) && Near(p2, 1f),+ $"the slot plays its pedal back on every pass ({p1:F0} → {p1up:F0} → {p2:F0})");+ e.StopAllSession();+ }++ // Recording a track fed through "MIDI In" prints the source clip's controllers into the take.+ private static IEnumerable<(bool, string)> Routed()+ {+ using var r = new Rig();+ var e = r.E;+ int src = e.AddInstrumentTrack();+ e.SetTrackBuiltinInstrument(src, 0);+ int c = e.AddMidiClip(src, 0, 4);+ e.SetClipNotes(src, c, new[] { new NotaNote(60, 0, 4, 0.8f) });+ e.SetMidiClipController(src, c, Mod, new[] { new AutomationPoint(0, 0f), new AutomationPoint(2, 1f) });+ e.SetTrackMidiSource(r.Track, src);+ r.Record();+ r.To(3.0);+ r.Stop();+ yield return (Near(r.At(Mod, 1.0), 0.5f, 0.05f) && Near(r.At(Mod, 2.5), 1f, 0.03f),+ $"recording a routed track prints its source's controllers into the take ({r.At(Mod, 1.0):F2} / {r.At(Mod, 2.5):F2})");+ }++ // A pedal pressed on the count-in lands before the record start, and the take's clip opens there.+ private static IEnumerable<(bool, string)> CountInPickup()+ {+ using var r = new Rig();+ var e = r.E;+ e.Seek(16.0);+ Beats(e, 0.01);+ e.SetCountIn(1);+ e.SetTrackArmed(r.Track, true);+ e.SetRecording(true); // 1 bar of count-in, then the take from beat 16+ Beats(e, 3.25);+ e.SendTrackController(r.Track, Sustain, 1f);+ Beats(e, 1.0);+ e.TrackNoteOn(r.Track, 60, 0.8f);+ Beats(e, 0.5);+ e.TrackNoteOff(r.Track, 60);+ e.SendTrackController(r.Track, Sustain, 0f);+ Beats(e, 0.5);+ e.Poll();+ e.SetRecording(false);+ e.Poll();+ e.TryGetClipInfo(r.Track, 0, out var ci);+ var sus = e.GetMidiClipController(r.Track, 0, Sustain);+ double at = sus.Length > 0 ? ci.StartBeat + sus[0].Beat : -1;+ yield return (sus.Length == 2 && Math.Abs(at - 15.25) < 0.03 && Math.Abs(ci.StartBeat - 15.25) < 0.03,+ $"a pedal pressed on the count-in is recorded there and the clip starts with it (pedal {at:F2}, clip {ci.StartBeat:F2})");+ e.StopTransport();+ }++ // A project saved before controllers existed (format v21) loads as it was: nothing added.+ private static IEnumerable<(bool, string)> OldProject()+ {+ string dir = Path.Combine(Path.GetTempPath(), "nota-smoke-ctl-v21-" + Guid.NewGuid().ToString("N") + ".nota");+ try+ {+ using (var src = new NotaEngine())+ {+ int t = src.AddInstrumentTrack();+ int c = src.AddMidiClip(t, 0, 4);+ src.SetClipNotes(t, c, new[] { new NotaNote(60, 0, 1, 0.8f) });+ ProjectService.Save(ProjectService.Capture(src, new TransportState(120.0, 1.0, false, false), new List<string>()), dir, src);+ }+ string manifest = Path.Combine(dir, ProjectService.ManifestName);+ var root = System.Text.Json.Nodes.JsonNode.Parse(File.ReadAllText(manifest))!.AsObject();+ root["formatVersion"] = 21;+ File.WriteAllText(manifest, root.ToJsonString());+ using var dst = new NotaEngine();+ var warn = ProjectService.Apply(ProjectService.Load(dir), dst, dir);+ int dt = dst.TryGetTrackInfo(0, out var ti) ? ti.Id : -1;+ yield return (dt > 0 && warn.Count == 0 && dst.GetClipNotes(dt, 0).Length == 1 && dst.GetMidiClipControllers(dt, 0).Length == 0,+ $"a format-v21 project loads unchanged, with no controllers (warnings {warn.Count})");+ }+ finally { try { Directory.Delete(dir, true); } catch { } }+ }++ // Saved with the project; a project without them loads with none.+ private static IEnumerable<(bool, string)> Persistence()+ {+ string dir = Path.Combine(Path.GetTempPath(), "nota-smoke-ctl-" + Guid.NewGuid().ToString("N") + ".nota");+ var transport = new TransportState(120.0, 1.0, false, false);+ try+ {+ using var src = new NotaEngine();+ int t = src.AddInstrumentTrack();+ int c = src.AddMidiClip(t, 0, 4);+ src.SetMidiClipController(t, c, Sustain, new[] { new AutomationPoint(1, 1f), new AutomationPoint(3, 0f) });+ src.SetMidiClipController(t, c, Wheel, new[] { new AutomationPoint(0, -0.5f), new AutomationPoint(2, 0.5f, 0.3f) });+ int plain = src.AddMidiClip(t, 8, 4);+ ProjectService.Save(ProjectService.Capture(src, transport, new List<string>()), dir, src);++ using var dst = new NotaEngine();+ var warn = ProjectService.Apply(ProjectService.Load(dir), dst, dir);+ int dt = dst.TryGetTrackInfo(0, out var ti) ? ti.Id : -1;+ var wh = dt > 0 ? dst.GetMidiClipController(dt, 0, Wheel) : Array.Empty<AutomationPoint>();+ yield return (dt > 0 && dst.GetMidiClipControllers(dt, 0).SequenceEqual(new[] { Sustain, Wheel })+ && dst.GetMidiClipController(dt, 0, Sustain).Length == 2 && wh.Length == 2 && wh[0].Value == -0.5f && wh[1].Curve == 0.3f+ && dst.GetMidiClipControllers(dt, 1).Length == 0,+ $"clip controllers are saved with the project and load back; a clip without them stays without ({Pts(wh)}, warnings {warn.Count})");+ }+ finally { try { Directory.Delete(dir, true); } catch { } }+ }+}diff --git a/tests/Nota.SmokeTest/Program.cs b/tests/Nota.SmokeTest/Program.csindex 80043d36..6d151ecf 100644--- a/tests/Nota.SmokeTest/Program.cs+++ b/tests/Nota.SmokeTest/Program.cs@@ -372,6 +372,14 @@ if (args.Length >= 1 && args[0] == "--live-record")Console.WriteLine(failures == 0 ? "LIVE RECORD PASSED" : $"LIVE RECORD FAILED ({failures})");return failures == 0 ? 0 : 1;}+// MIDI controllers alone (fast iteration): `--midi-ctl`. Also part of the full run.+if (args.Length >= 1 && args[0] == "--midi-ctl")+{+ Console.WriteLine("-- midi controllers --");+ foreach (var (ok, label) in MidiControllerTests.Run()) Check(ok, label);+ Console.WriteLine(failures == 0 ? "MIDI CTL PASSED" : $"MIDI CTL FAILED ({failures})");+ return failures == 0 ? 0 : 1;+}// MPE alone (fast iteration): `--mpe`. Also part of the full run.if (args.Length >= 1 && args[0] == "--mpe"){@@ -13688,9 +13696,24 @@ Console.WriteLine("-- MCP tools --");}).Wait();var mcpNotes = mcpMidi.GetClipNotes(mcpT, mcpClip).Result;Check(mcpNotes.Length == 3 && mcpNotes[0].Pitch == 60 && Math.Abs(mcpNotes[2].Length - 2) < 1e-3, $"MCP set/get_clip_notes round-trip ({mcpNotes.Length})");+ mcpMidi.SetClipController(mcpT, mcpClip, "sustain", new[]+ {+ new Nota.Mcp.Tools.MidiTools.ControllerPoint(0, 1f), new Nota.Mcp.Tools.MidiTools.ControllerPoint(3.9, 0f),+ }).Wait();+ mcpMidi.SetClipController(mcpT, mcpClip, "cc11", new[] { new Nota.Mcp.Tools.MidiTools.ControllerPoint(0, 0.5f) }).Wait();+ var mcpCtl = mcpMidi.GetClipControllers(mcpT, mcpClip).Result;+ bool mcpBadCtl = false;+ try { mcpMidi.SetClipController(mcpT, mcpClip, "cc121", Array.Empty<Nota.Mcp.Tools.MidiTools.ControllerPoint>()).Wait(); }+ catch (AggregateException ex) when (ex.InnerException is ArgumentException) { mcpBadCtl = true; }+ catch (ArgumentException) { mcpBadCtl = true; }+ Check(mcpCtl.Length == 2 && mcpCtl[0].Ctl == 11 && mcpCtl[0].Name == "Expression" && mcpCtl[1].Name == "Sustain"+ && mcpCtl[1].Points.Length == 2 && mcpBadCtl,+ $"MCP set/get_clip_controller round-trip by name and number; a reserved CC is refused ({mcpCtl.Length})");var mcpCons = mcpMidi.ConsolidateClips(new[] { mcpT }, 0, 4).Result;Check(mcpCons.Length == 1 && mcpCons[0].TrackId == mcpT && mcpMidi.GetClipNotes(mcpT, mcpCons[0].ClipIndex).Result.Length == 3,"MCP consolidate_clips keeps the notes in one clip");+ Check(mcpCons.Length == 1 && mcpMidi.GetClipControllers(mcpT, mcpCons[0].ClipIndex).Result.Length == 2,+ "consolidate keeps the clip's controller curves");int mcpDev = mcpDevices.AddDevice(mcpT, 2).Result; // 2 = ReverbCheck(mcpDev >= 0 && mcpEng.TrackDeviceBuiltinKind(mcpT, mcpDev) == 2, "MCP add_device (Reverb)");@@ -14647,6 +14670,8 @@ Console.WriteLine("-- mpe: per-note expression --");foreach (var (ok, label) in MpeTests.Run()) Check(ok, label);Console.WriteLine("-- live midi recording --");foreach (var (ok, label) in LiveRecordTests.Run()) Check(ok, label);+Console.WriteLine("-- midi controllers --");+foreach (var (ok, label) in MidiControllerTests.Run()) Check(ok, label);Console.WriteLine("-- loop seam --");foreach (var (ok, label) in LoopSeamTests.Run()) Check(ok, label);Console.WriteLine("-- loop record mode --");