Skip to content

armgit / nota

Public Imported from GitHub
0

Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.

(fix) A tempo set over MCP shows in the transport bar and is saved (#162)

lockstock7317e9e97711d0
diff --git a/.specify/bugs/mcp-tempo-ui-sync/assessment.md b/.specify/bugs/mcp-tempo-ui-sync/assessment.md
new file mode 100644
index 00000000..c738cf8a
--- /dev/null
+++ b/.specify/bugs/mcp-tempo-ui-sync/assessment.md
@@ -0,0 +1,99 @@
+# Bug Assessment: a tempo set over MCP never reaches the transport bar, and the stale value is saved
+
+- **Slug**: mcp-tempo-ui-sync
+- **Created**: 2026-10-17
+- **Source**: pasted text (user observation, Nota 0.55.1 on Ubuntu 26.04)
+- **Verdict**: valid
+- **Severity**: high
+
+## Report (verbatim or summarized)
+
+> yes, the tempo is stating 121 BPM in the UI, so it seems changes from the API don't update
+> the field
+
+The reporter drives the tempo from a hardware knob through MCP `set_tempo`. After a series of
+`set_tempo` calls (140 → 90 → 140 → 110), the engine played at 110 BPM while the transport bar
+still showed 121.
+
+## Symptom
+
+`set_tempo` over MCP changes the engine's tempo, but `TransportViewModel.Bpm` keeps its old
+value. So the BPM field shows the wrong tempo. Worse, everything that reads the view-model gets
+the stale tempo: saving, autosave/crash recovery, and the export dialog. Expected: a tempo set
+from MCP shows in the transport bar and is what gets saved, just like a tempo typed into the
+field.
+
+## Reproduction
+
+1. Open a project at 120 BPM with the MCP server enabled.
+2. Call `set_tempo` with `bpm: 90`.
+3. `get_transport` reports `bpm: 90`, but the transport bar still shows 120.
+4. Save the project and reopen it: it opens at 120. [NEEDS CLARIFICATION: the save step is
+ inferred from `TransportSnapshot()` and not yet run end-to-end; it will be verified in
+ `/speckit-bug-test`.]
+
+## Suspected Code Paths
+
+- `src/managed/Nota.Mcp/Tools/TransportTools.cs:33`: `SetTempo` calls `E.SetBpm` directly,
+ bypassing `TransportViewModel`.
+- `src/managed/Nota.Presentation/ViewModels/TransportViewModel.cs:188` (`Tick`): already
+ follows the engine for state that MCP can change. Line 200 says "The loop record mode can
+ also be set from outside the UI (MCP): follow the engine". It doesn't do this for `Bpm`.
+- `src/managed/Nota.App/MainWindow.Recovery.cs:26` (`TransportSnapshot`) and
+ `src/managed/Nota.App/MainWindow.Files.cs:63` (export): read `_vm.Transport.Bpm`, so they save
+ and export the stale tempo.
+- `src/managed/Nota.App/MainWindow.Remote.cs:161`: the Remote's `SetBpm` goes through
+ `vm.Transport.Bpm`, so it doesn't have this bug.
+
+## Root Cause Hypothesis
+
+Two writers set the tempo, and only one goes through the view-model. Nothing reconciles them:
+`Tick()` follows the engine for position, play state and loop record mode, but not for tempo.
+`OnBpmChanged` writes to the engine but never reads from it. Confidence: high. The divergence
+was observed directly (engine 110, field 121).
+
+## Proposed Remediation
+
+**Preferred**: follow the engine's tempo in `TransportViewModel.Tick()`, in the same way as the
+existing `LoopRecordReplace` line. Read `_engine.Bpm`, round it to the field's 2 decimal places,
+and assign `Bpm` only when it differs. The assignment raises `PropertyChanged`, so the BPM field
+updates through the existing handler. The `OnBpmChanged` echo then calls `SetBpm` with the value
+the engine already has, which changes nothing. `Tick()` runs on the UI clock, so this picks up
+any out-of-band tempo source, not just MCP.
+
+**Alternatives**:
+- Route MCP `set_tempo` through the view-model, as the Remote does. `Nota.Mcp` is Avalonia-free
+ and only sees `IAudioEngine`, so it would need a new port into the presentation layer. It
+ also wouldn't help other out-of-band writers.
+
+**Files likely to change**:
+- `src/managed/Nota.Presentation/ViewModels/TransportViewModel.cs`
+- `CHANGELOG.md`
+
+**Tests to add or update**:
+- The smoke test drives the engine, not the view-model. Verify by hand: `set_tempo` over MCP
+ updates the BPM field within a frame, and a saved and reopened project keeps the MCP-set
+ tempo. Also check that dragging the BPM field still works (no fight with the follow line
+ during a drag).
+
+## Risks & Considerations
+
+- Fighting the user mid-drag: `OnBpmChanged` sets the engine synchronously, so by the next
+ `Tick` the engine already matches the field. Compare with a small tolerance (rounded to 2
+ decimal places) so float/decimal round-trips never cause a correction.
+- Interaction with `tempo-unwarped-redraw`: once that fix is in, a tempo that arrives through
+ `Tick` also raises `Bpm`'s `PropertyChanged`, so the arrangement redraws as well. The MCP path
+ already refreshes, and the coalesced refresh makes the extra one cheap.
+
+## Related (out of scope)
+
+The same class of bug probably affects other transport settings that MCP can change:
+`set_time_signature`, `set_metronome`, `set_master_volume` and `set_loop` also call the engine
+directly. Time signature, metronome and master volume have no engine getters on `IAudioEngine`
+(no `TimeSigNumerator`/`Metronome`/`MasterVolume` properties), so following them would need
+new C ABI reads. The loop already has `SyncLoop()`. These are left for a separate report, and
+this fix stays one logical change.
+
+## Open Questions
+
+- None.
diff --git a/.specify/bugs/mcp-tempo-ui-sync/fix.md b/.specify/bugs/mcp-tempo-ui-sync/fix.md
new file mode 100644
index 00000000..08d35163
--- /dev/null
+++ b/.specify/bugs/mcp-tempo-ui-sync/fix.md
@@ -0,0 +1,98 @@
+# Bug Fix: a tempo set over MCP never reaches the transport bar, and the stale value is saved
+
+- **Slug**: mcp-tempo-ui-sync
+- **Fixed**: 2026-10-17
+- **Assessment**: ./assessment.md
+- **Status**: applied
+
+## Summary
+
+`TransportViewModel.Tick()` now follows the engine's tempo, like it already follows the loop
+record mode. A tempo set outside the UI (MCP `set_tempo`, or a controller driving it) then
+reaches the BPM field and is what saving, autosave and export read. The field's own changes
+are guarded while they are in flight, so a drag never snaps back.
+
+## Changes
+
+| File | Change | Notes |
+|------|--------|-------|
+| `src/managed/Nota.Presentation/ViewModels/TransportViewModel.cs` | modified | `FollowEngineBpm()` called from `Tick()`; `OnBpmChanged` records the in-flight tempo; `_followingBpm` suppresses the echo |
+| `tests/Nota.SmokeTest/TempoFollowTests.cs` | added test | 9 checks, `RenderOffline` standing in for the audio thread |
+| `tests/Nota.SmokeTest/Program.cs` | modified | runs `TempoFollowTests` in the full smoke run, after loop record mode |
+| `CHANGELOG.md` | modified | `Fixed` entry under `[Unreleased]` |
+
+```csharp
+partial void OnBpmChanged(decimal value)
+{
+ if (_followingBpm) return; // the engine already has it (unrounded): don't echo it back
+ _sentBpm = (double)value;
+ _sentBpmAt = Environment.TickCount64;
+ _engine.SetBpm((double)value);
+}
+
+private void FollowEngineBpm()
+{
+ double engineBpm = _engine.Bpm;
+ if (_sentBpm is double sent)
+ {
+ bool landed = Math.Abs(engineBpm - sent) < 1e-6;
+ if (!landed && Environment.TickCount64 - _sentBpmAt < SentBpmTimeoutMs) return;
+ _sentBpm = null;
+ }
+ decimal bpm = Math.Round((decimal)engineBpm, 2); // the field's resolution
+ if (bpm == Bpm) return;
+ _followingBpm = true;
+ Bpm = bpm;
+ _followingBpm = false;
+}
+```
+
+## Tests Added or Updated
+
+- `TempoFollowTests`: an outside tempo reaches the field; it shows rounded to hundredths
+ without the rounded value being written back to the engine; consecutive outside changes
+ are each followed; a tick before the engine applies the field's own tempo keeps the
+ field's value; a drag that runs ahead of the engine keeps its latest value and lands on
+ it; outside changes are followed again once the field's own change has landed.
+
+## Local Verification
+
+- Commands run, Ubuntu 26.04 x64, .NET SDK 10.0.112:
+ - `dotnet build Nota.sln -c Release -nodeReuse:false -m:1` → 0 errors, no new warnings.
+ (The parallel build crashes on this machine with `Internal CLR error (0x80131506)`
+ before compiling anything, on `develop` as well. It's an SDK problem on this host and
+ unrelated to the change.)
+ - `dotnet run --project tests/Nota.SmokeTest -c Release` → `SMOKE TEST PASSED`; all
+ 9 `tempo follow` checks pass.
+- The tests fail without the fix. Against `develop`'s `TransportViewModel.cs`, the 5 "follow
+ an outside tempo" checks fail. Against the assessment's naive remediation (follow the
+ engine in `Tick` with no in-flight guard), 4 checks fail: the field snaps back mid-drag,
+ and the rounded value is echoed to the engine.
+- Manual checks: pending (`/speckit-bug-test`). These are: MCP `set_tempo` updates the BPM
+ field in the running app, a save and reopen keeps it, and a drag of the field is smooth.
+
+## Deviations from Assessment
+
+- The assessment said the `OnBpmChanged` echo would be harmless, because the engine would
+ already match the field by the next `Tick`. That's wrong: `Engine::setBpm` only queues a
+ `SetBpm` command for the audio thread, and `Engine::bpm()` reads the transport's value,
+ which updates when the audio thread drains the queue (`Engine.cpp:438`). A naive follow
+ in `Tick` reads the old tempo after a field edit and snaps the field back mid-drag.
+ The fix adds two things for this:
+ - an in-flight guard: wait until the engine reports the sent tempo, with a 1 s timeout for
+ when no audio thread is draining commands.
+ - an echo guard (`_followingBpm`, like the existing `_syncingLoop`): following the engine
+ never writes back to it.
+- Following doesn't write the rounded value back to the engine (an outside 110.333 shows as
+ 110.33 and keeps playing at 110.333). The assessment assumed the echo would normalise
+ the engine to the field. Not echoing keeps follow read-only, so it can't race a second
+ outside change.
+
+## Follow-ups
+
+- Time signature, metronome and master volume set over MCP probably diverge from the
+ view-model in the same way. That needs engine getters (see the assessment, *Related*).
+ The loop could use the existing `SyncLoop()`.
+- `Engine::bpm()` is read from the UI thread while the audio thread writes `bpm_` (a plain
+ `double`). This predates the fix, since MCP `get_transport` already reads it, but it's
+ worth making atomic.
diff --git a/.specify/bugs/mcp-tempo-ui-sync/test.md b/.specify/bugs/mcp-tempo-ui-sync/test.md
new file mode 100644
index 00000000..202d1925
--- /dev/null
+++ b/.specify/bugs/mcp-tempo-ui-sync/test.md
@@ -0,0 +1,56 @@
+# Bug Verification: a tempo set over MCP never reaches the transport bar, and the stale value is saved
+
+- **Slug**: mcp-tempo-ui-sync
+- **Tested**: 2026-10-18
+- **Assessment**: ./assessment.md
+- **Fix**: ./fix.md
+- **Result**: verified
+
+## Summary
+
+A tempo set over MCP now reaches the BPM field, is saved with the project and comes back on
+reopen. Dragging the field doesn't snap back. The new smoke checks pass with the fix and
+fail without it, and the full smoke test passes.
+
+## Checks Performed
+
+| Check | Command / Action | Result | Notes |
+|-------|------------------|--------|-------|
+| Reproduction (post-fix) | Local build, tempo driven over MCP `set_tempo` from a hardware knob (a Maschine Mikro MK2 through a HID→MCP bridge) | pass | Reporter: "knob updated the field" |
+| Save keeps the MCP tempo | Set 97 BPM from the knob, save `test.nota`, read `project.json` | pass | `"bpm": 97` in the saved file |
+| Reopen keeps it | Relaunch, project reopens, MCP `get_transport` | pass | `"bpm":97`; reporter: "saved tempo loaded correctly" |
+| No snap-back mid-drag | Drag the BPM field quickly back and forth | pass | Reporter: "seemed stable" |
+| New / updated tests | `dotnet run --project tests/Nota.SmokeTest -c Release` (`-- tempo follow --`) | pass | 9/9 |
+| Tests catch the bug | Same, against `develop`'s `TransportViewModel.cs` | fail (expected) | 5 follow checks fail |
+| Tests catch the race | Same, against a naive follow (no in-flight guard) | fail (expected) | 4 checks fail: snap-back mid-drag, rounded echo |
+| Regression suite | full smoke test | pass | `SMOKE TEST PASSED` |
+| Build | `dotnet build Nota.sln -c Release -nodeReuse:false -m:1` | pass | 0 errors, no new warnings |
+
+## Output Excerpts
+
+```
+-- tempo follow --
+ [PASS] an outside tempo change reaches the BPM field
+ [PASS] …rounded to the field's hundredths
+ [PASS] …without echoing the rounded value back to the engine
+ [PASS] consecutive outside changes are each followed
+ [PASS] a tick before the engine applies the field's tempo keeps it
+ [PASS] …and once applied, field and engine agree
+ [PASS] a drag ahead of the engine keeps the latest value
+ [PASS] …and lands on it
+ [PASS] outside changes are followed again after the field's own lands
+SMOKE TEST PASSED
+```
+
+## Residual Risks
+
+- The 1 s in-flight timeout isn't covered by a test (that would need a 1 s wait in the
+ smoke run). It only matters when no audio thread drains engine commands.
+- Tested on Linux only (Ubuntu 26.04 x64). The change is platform-neutral view-model code.
+- Other transport settings set over MCP (time signature, metronome, master volume, loop)
+ still don't reach the view-model. They're out of scope (see the assessment, *Related*).
+
+## Recommendation
+
+Close the bug. It's verified end-to-end on Linux, and the smoke run now guards against
+regressions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 239e737f..4d78918f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -82,6 +82,11 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.
Windows and Linux) always starts a new track.
### Fixed
+- **A tempo set over MCP shows in the transport bar and is saved**: `set_tempo` (and
+ anything driving it, such as a hardware controller) changed the tempo you hear, but the
+ BPM field kept the old number, and saving, autosave and export used that stale tempo, so
+ a reopened project came back at the wrong speed. The transport bar now follows the
+ engine's tempo, and dragging the field never snaps back while the engine catches up.
- **Un-warped audio clips follow the tempo as you change it**: an un-warped clip keeps its
length in seconds, so a new tempo makes it longer or shorter in bars. Changing the tempo
in the transport bar now shows that at once, while you drag, so a clip can be lined up
diff --git a/src/managed/Nota.Presentation/ViewModels/TransportViewModel.cs b/src/managed/Nota.Presentation/ViewModels/TransportViewModel.cs
index cd0e4910..434f3c0c 100644
--- a/src/managed/Nota.Presentation/ViewModels/TransportViewModel.cs
+++ b/src/managed/Nota.Presentation/ViewModels/TransportViewModel.cs
@@ -65,7 +65,21 @@ public partial class TransportViewModel(IAudioEngine engine) : ObservableObject
private bool _syncingLoop;
- partial void OnBpmChanged(decimal value) => _engine.SetBpm((double)value);
+ // The tempo this view-model last sent and is waiting to read back. SetBpm only queues
+ // the change for the audio thread, so until the engine reports it, Tick must not
+ // mistake the old tempo for an outside change and snap the field back mid-drag.
+ private double? _sentBpm;
+ private long _sentBpmAt;
+ private const long SentBpmTimeoutMs = 1000; // no audio thread draining commands: stop waiting
+ private bool _followingBpm; // reflecting the engine's tempo, not a user edit
+
+ partial void OnBpmChanged(decimal value)
+ {
+ if (_followingBpm) return; // the engine already has it (unrounded): don't echo it back
+ _sentBpm = (double)value;
+ _sentBpmAt = Environment.TickCount64;
+ _engine.SetBpm((double)value);
+ }
partial void OnTimeSigNumeratorChanged(int value) => _engine.SetTimeSignature(value, TimeSigDenominator);
partial void OnTimeSigDenominatorChanged(int value) => _engine.SetTimeSignature(TimeSigNumerator, value);
partial void OnMasterVolumeChanged(double value)
@@ -200,6 +214,26 @@ public partial class TransportViewModel(IAudioEngine engine) : ObservableObject
// The loop record mode can also be set from outside the UI (MCP): follow the engine.
bool replace = _engine.LoopRecordReplace;
if (replace != LoopRecordReplace) LoopRecordReplace = replace;
+ FollowEngineBpm();
+ }
+
+ /// <summary>The tempo can also be set from outside the UI (MCP, a controller driving
+ /// it): follow the engine, so the BPM field shows it and saving keeps it. Our own
+ /// change is still in flight until the engine reports it, so wait for that first.</summary>
+ private void FollowEngineBpm()
+ {
+ double engineBpm = _engine.Bpm;
+ if (_sentBpm is double sent)
+ {
+ bool landed = Math.Abs(engineBpm - sent) < 1e-6;
+ if (!landed && Environment.TickCount64 - _sentBpmAt < SentBpmTimeoutMs) return;
+ _sentBpm = null;
+ }
+ decimal bpm = Math.Round((decimal)engineBpm, 2); // the field's resolution
+ if (bpm == Bpm) return;
+ _followingBpm = true;
+ Bpm = bpm;
+ _followingBpm = false;
}
/// <summary>The count-in as negative bars counting up to the start: −2.1 … −2.4, −1.1 … −1.4.</summary>
diff --git a/tests/Nota.SmokeTest/Program.cs b/tests/Nota.SmokeTest/Program.cs
index cbfa4b6c..3e126512 100644
--- a/tests/Nota.SmokeTest/Program.cs
+++ b/tests/Nota.SmokeTest/Program.cs
@@ -14790,6 +14790,8 @@ Console.WriteLine("-- loop seam --");
foreach (var (ok, label) in LoopSeamTests.Run()) Check(ok, label);
Console.WriteLine("-- loop record mode --");
foreach (var (ok, label) in LoopRecordModeTests.Run()) Check(ok, label);
+Console.WriteLine("-- tempo follow --");
+foreach (var (ok, label) in TempoFollowTests.Run()) Check(ok, label);
Console.WriteLine("-- nota keys --");
foreach (var (ok, label) in KeysTests.Run()) Check(ok, label);
Console.WriteLine("-- instrument on/off --");
diff --git a/tests/Nota.SmokeTest/TempoFollowTests.cs b/tests/Nota.SmokeTest/TempoFollowTests.cs
new file mode 100644
index 00000000..ed719cb6
--- /dev/null
+++ b/tests/Nota.SmokeTest/TempoFollowTests.cs
@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// The transport bar follows a tempo set outside the UI (MCP set_tempo, .specify/bugs/
+// mcp-tempo-ui-sync), so the BPM field shows it and saving keeps it. SetBpm only queues the
+// change for the audio thread; here RenderOffline stands in for that thread, so these pin
+// both directions: an outside tempo reaches the view-model, and the field's own change is
+// never snapped back by a Tick that still reads the old tempo.
+
+using Nota.Infrastructure;
+using Nota.Presentation;
+
+namespace Nota.SmokeTest;
+
+internal static class TempoFollowTests
+{
+ private const int Chunk = 256;
+ private const double Sr = 48000.0;
+
+ public static IEnumerable<(bool, string)> Run()
+ {
+ using var e = new NotaEngine();
+ var vm = new TransportViewModel(e) { Bpm = 120 };
+ Apply(e); vm.Tick();
+
+ // An outside tempo (what MCP set_tempo does) reaches the view-model on the next tick.
+ e.SetBpm(90); Apply(e); vm.Tick();
+ yield return (vm.Bpm == 90m, "an outside tempo change reaches the BPM field");
+
+ // The field's resolution is hundredths, so an outside 110.333 shows as 110.33.
+ e.SetBpm(110.333); Apply(e); vm.Tick();
+ yield return (vm.Bpm == 110.33m, "…rounded to the field's hundredths");
+ Apply(e); vm.Tick(); // following never writes back: the engine keeps its exact tempo
+ yield return (Math.Abs(e.Bpm - 110.333) < 1e-9 && vm.Bpm == 110.33m, "…without echoing the rounded value back to the engine");
+
+ // Two outside changes in a row (a controller knob turning): both are followed.
+ e.SetBpm(95); Apply(e); vm.Tick();
+ e.SetBpm(96); Apply(e); vm.Tick();
+ yield return (vm.Bpm == 96m, "consecutive outside changes are each followed");
+
+ // The user's own change is in flight until the engine applies it: a tick that still
+ // reads the old tempo must not snap the field back.
+ vm.Bpm = 121; vm.Tick();
+ yield return (vm.Bpm == 121m, "a tick before the engine applies the field's tempo keeps it");
+ Apply(e); vm.Tick();
+ yield return (vm.Bpm == 121m && Math.Abs(e.Bpm - 121) < 1e-9, "…and once applied, field and engine agree");
+
+ // A fast drag: several sends queue up before the engine catches up; ticks in between
+ // must keep the latest value, not the tempo the engine still reports.
+ vm.Bpm = 122; vm.Bpm = 123; vm.Bpm = 124; vm.Tick();
+ yield return (vm.Bpm == 124m, "a drag ahead of the engine keeps the latest value");
+ Apply(e); vm.Tick();
+ yield return (vm.Bpm == 124m && Math.Abs(e.Bpm - 124) < 1e-9, "…and lands on it");
+
+ // After the field's change has landed, an outside change is followed again.
+ e.SetBpm(100); Apply(e); vm.Tick();
+ yield return (vm.Bpm == 100m, "outside changes are followed again after the field's own lands");
+ }
+
+ // Stand-in for the audio thread: one render drains the queued commands.
+ private static void Apply(NotaEngine e) => e.RenderOffline(new float[Chunk * 2], Chunk, Sr);
+}