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.

31.4 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
//
// Articulation maps through the engine (specs/085): the note's articulation id crosses the C ABI
// intact (the NotaNoteData / NotaNote layouts agree), the track MIDI offset is clamped, copied with
// the track and undone with it, moves playback by the requested milliseconds without moving notes,
// and both survive saving and reopening; a v29 project opens with neither.
// Runnable alone: `dotnet run --project tests/Nota.SmokeTest -- --articulations`.

using System.Text.Json.Nodes;
using Nota.Application.Midi;
using Nota.Infrastructure;

namespace Nota.SmokeTest;

internal static class ArticulationEngineTests
{
    private const int Block = 512, Rate = 48000;

    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, Rate);
            for (int i = 0; i < Block; i++) all[k * Block + i] = (b[i * 2] + b[i * 2 + 1]) * 0.5f;
        }
        return all;
    }

    /// <summary>First sample louder than a quiet threshold, or -1.</summary>
    private static int Onset(float[] x)
    {
        for (int i = 0; i < x.Length; i++) if (Math.Abs(x[i]) > 1e-3f) return i;
        return -1;
    }

    /// <summary>Where one note at beat 1 (0.5 s at 120 BPM) starts sounding, with the track at <paramref name="offsetMs"/>.</summary>
    private static int OnsetWithOffset(double offsetMs)
    {
        using var e = new NotaEngine();
        e.SetBpm(120);
        int t = e.AddInstrumentTrack();
        e.SetTrackBuiltinInstrument(t, 0);
        int c = e.AddMidiClip(t, 0, 4);
        e.SetClipNotes(t, c, new[] { new NotaNote(57, 1.0, 1.0, 0.9f) });
        e.SetTrackMidiOffsetMs(t, offsetMs);
        Render(e, 2);                                 // let the graph settle before the clock starts
        e.StopTransport(); e.Seek(0); e.Play();
        return Onset(Render(e, 94));                  // ~1 s
    }

    // The clip tools (generate / transform) keep articulations (T011): notes outside the selection
    // pass through untouched, and notes made from a note play that note's articulation.
    private static IEnumerable<(bool ok, string label)> ClipTools()
    {
        var ctx = new MidiToolContext { LengthBeats = 4, Grid = 0.25, ScaleOn = false, ScaleRoot = 0, ScaleMask = MidiScales.MaskAt(0), Seed = 11 };
        var clip = new[]
        {
            new NotaNote(60, 0.0, 2.0, 0.8f) { ArticulationId = 1 },
            new NotaNote(64, 0.0, 2.0, 0.8f) { ArticulationId = 2 },
            new NotaNote(72, 2.0, 2.0, 0.8f) { ArticulationId = 9 },   // outside the selection below
        };
        var selection = new[] { 0, 1 };

        int lost = 0;
        string firstLost = "";
        foreach (var tool in MidiToolCatalog.All)
        {
            var outp = MidiToolRunner.Apply(tool, clip, selection, tool.NewSettings(), ctx);
            bool kept = outp.Any(n => n.Pitch == 72 && n.ArticulationId == 9) || !outp.Any(n => n.Pitch == 72 && Math.Abs(n.StartBeat - 2.0) < 1e-9);
            if (!kept) { lost++; if (firstLost.Length == 0) firstLost = tool.Id; }
        }
        yield return (lost == 0, $"articulations: no clip tool strips the articulation of a note outside its selection ({lost} did{(lost > 0 ? ", first " + firstLost : "")})");

        var trill = MidiTransforms.Ornament.NewSettings();
        trill.Set("type", 1);
        trill.Set("chance", 1.0);
        var orn = MidiToolRunner.Apply(MidiTransforms.Ornament, new[] { new NotaNote(60, 0, 2, 0.8f) { ArticulationId = 4 } }, null, trill, ctx);
        yield return (orn.Count > 1 && orn.All(n => n.ArticulationId == 4),
            $"articulations: a trill's notes all play the ornamented note's articulation ({orn.Count} notes)");

        var arp = MidiToolRunner.Apply(MidiTransforms.Arpeggiate, clip[..2], null, MidiTransforms.Arpeggiate.NewSettings(), ctx);
        bool byChordNote = arp.Count > 2 && arp.All(n => n.ArticulationId == ((n.Pitch % 12) == 0 ? 1 : (n.Pitch % 12) == 4 ? 2 : -1));
        yield return (byChordNote, $"articulations: each arpeggio step plays the articulation of the chord note it came from ({arp.Count} notes)");
    }

    // A map on a track (T016–T023): the engine validates the table, keeps the map JSON, undoes and
    // redoes it, copies it with the track, and a project saves and reopens it — or opens without it.
    private static IEnumerable<(bool ok, string label)> MapOnTrack()
    {
        var map = ArticulationFileTests.Full();
        string json = Nota.Application.Articulations.ArticulationMapFile.Write(map);
        using (var e = new NotaEngine())
        {
            int t = e.AddInstrumentTrack();
            int audio = e.AddAudioTrack();
            e.ClearUndoHistory();
            yield return (e.GetTrackArticulationMapJson(t) is null, "articulations: a new track has no map");
            yield return (Nota.Application.Articulations.ArticulationMapAssignment.Assign(e, t, map) && e.GetTrackArticulationMapJson(t) == json,
                "articulations: a compiled map is accepted and the track keeps its JSON exactly");
            var readBack = Nota.Application.Articulations.ArticulationMapAssignment.Read(e, t);
            yield return (readBack is not null && Nota.Application.Articulations.ArticulationMapFile.Write(readBack) == json,
                "articulations: the map read back from the track equals the one given");

            // Every rule of the table, each refused with nothing changed.
            var ok = Nota.Application.Articulations.ArticulationMapCompiler.Compile(map);
            NotaArticulationEntry[] E(params NotaArticulationEntry[] x) => x;
            var bad = new List<(string why, int def, NotaArticulationEntry[] en, NotaArticulationAction[] ac)>
            {
                ("ids not ascending", 0, E(ok.Entries[1], ok.Entries[0]), ok.Actions),
                ("a repeated id", 0, E(ok.Entries[0], ok.Entries[0]), ok.Actions),
                ("an id of 0", 0, E(ok.Entries[0] with { Id = 0 }), ok.Actions),
                ("an action range past the array", 0, E(ok.Entries[0] with { ActionCount = 99 }), ok.Actions),
                ("a negative action start", 0, E(ok.Entries[0] with { ActionStart = -1 }), ok.Actions),
                ("an unknown trigger mode", 0, E(ok.Entries[0] with { TriggerMode = 5 }), ok.Actions),
                ("a NaN offset", 0, E(ok.Entries[0] with { OffsetMs = double.NaN }), ok.Actions),
                ("an offset past 2000 ms", 0, E(ok.Entries[0] with { OffsetMs = 2500 }), ok.Actions),
                ("a negative lead", 0, E(ok.Entries[0] with { LeadMs = -1 }), ok.Actions),
                ("a default that isn't an entry", 5, ok.Entries, ok.Actions),
                ("data past 127", 0, ok.Entries, ok.Actions.Select((x, i) => i == 0 ? x with { Data1 = 128 } : x).ToArray()),
                ("channel 17", 0, ok.Entries, ok.Actions.Select((x, i) => i == 0 ? x with { Channel = 17 } : x).ToArray()),
                ("an unknown action kind", 0, ok.Entries, ok.Actions.Select((x, i) => i == 0 ? x with { Kind = 9 } : x).ToArray()),
            };
            var refusedWrongly = new List<string>();
            foreach (var (why, def, en, ac) in bad)
                if (e.SetTrackArticulationMap(t, def, en, ac, "{}") || e.GetTrackArticulationMapJson(t) != json) refusedWrongly.Add(why);
            yield return (refusedWrongly.Count == 0, $"articulations: the engine refuses a broken table and keeps the map it had ({bad.Count} cases{(refusedWrongly.Count > 0 ? "; not refused: " + string.Join(", ", refusedWrongly) : "")})");
            yield return (!e.SetTrackArticulationMap(audio, ok.DefaultId, ok.Entries, ok.Actions, json) && e.GetTrackArticulationMapJson(audio) is null,
                "articulations: an audio track can't take a map");
            yield return (!e.SetTrackArticulationMap(9999, ok.DefaultId, ok.Entries, ok.Actions, json), "articulations: no such track is refused");
            yield return (e.SetTrackArticulationMap(t, 0, Array.Empty<NotaArticulationEntry>(), Array.Empty<NotaArticulationAction>(), "{}")
                          && e.GetTrackArticulationMapJson(t) == "{}", "articulations: an empty map is allowed (it sends nothing)");

            // Undo and redo, one step each.
            e.Undo();
            yield return (e.GetTrackArticulationMapJson(t) == json, "articulations: undo restores the previous map");
            e.Undo();
            yield return (e.GetTrackArticulationMapJson(t) is null, "articulations: undoing the first assignment leaves no map");
            e.Redo();
            yield return (e.GetTrackArticulationMapJson(t) == json, "articulations: redo assigns it again");
            yield return (e.ClearTrackArticulationMap(t) && e.GetTrackArticulationMapJson(t) is null, "articulations: clearing removes the map");
            e.Undo();
            yield return (e.GetTrackArticulationMapJson(t) == json, "articulations: undoing the clear brings it back");
            int dup = e.DuplicateTrack(t);
            yield return (dup > 0 && e.GetTrackArticulationMapJson(dup) == json, "articulations: a duplicated track keeps its map");
            int plain = e.AddInstrumentTrack();
            bool couldUndo = e.CanUndo;
            e.ClearUndoHistory();
            yield return (couldUndo && e.ClearTrackArticulationMap(plain) && !e.CanUndo,
                "articulations: clearing an instrument track with no map succeeds and adds no undo step");
            yield return (!e.ClearTrackArticulationMap(audio), "articulations: an audio track refuses a clear too");
        }

        // Save and reopen; a damaged map in a project opens without it.
        string bundle = Path.Combine(Path.GetTempPath(), "nota-artmap-" + Guid.NewGuid().ToString("N") + ".nota");
        try
        {
            using var e = new NotaEngine();
            int t = e.AddInstrumentTrack();
            e.AddInstrumentTrack();   // a second one without a map
            Nota.Application.Articulations.ArticulationMapAssignment.Assign(e, t, map);
            var doc = ProjectService.Capture(e, new TransportState(120.0, 1.0, false, false), new List<string>());
            yield return (doc.Tracks.Count(d => d.ArticulationMap is not null) == 1, "articulations: only the track with a map writes one");
            ProjectService.Save(doc, bundle, e);

            using var e2 = new NotaEngine();
            var warnings = ProjectService.Apply(ProjectService.Load(bundle), e2, bundle);
            var jsons = new List<string?>();
            for (int i = 0; i < e2.TrackCount; i++)
                if (e2.TryGetTrackInfo(i, out var ti) && ti.IsInstrument) jsons.Add(e2.GetTrackArticulationMapJson(ti.Id));
            yield return (jsons.Count == 2 && jsons[0] == json && jsons[1] is null && warnings.Count == 0,
                "articulations: the map survives saving and reopening exactly");

            // The same document with its map damaged: it opens, the track has no map, a warning says why.
            var broken = ProjectService.Load(bundle);
            broken.Tracks.First(d => d.ArticulationMap is not null).ArticulationMap = new System.Text.Json.Nodes.JsonObject { ["format"] = "nonsense" };
            using var e3 = new NotaEngine();
            var w3 = ProjectService.Apply(broken, e3, bundle);
            bool noMap = true;
            for (int i = 0; i < e3.TrackCount; i++)
                if (e3.TryGetTrackInfo(i, out var ti) && e3.GetTrackArticulationMapJson(ti.Id) is not null) noMap = false;
            yield return (noMap && w3.Count >= 1 && e3.TrackCount == 2, $"articulations: a project with a damaged map still opens, without it, and warns ({w3.Count})");
        }
        finally
        {
            try { if (Directory.Exists(bundle)) Directory.Delete(bundle, recursive: true); } catch (IOException) { }
        }
    }

    // Phase 4/5 (US2, US3): the engine's own check of the scheduler, then the articulation offset
    // moving real notes, through the C ABI, at two tempos.
    private static IEnumerable<(bool ok, string label)> Playback()
    {
        using (var e = new NotaEngine())
        {
            int code = e.ArticulationSelfTest();
            yield return (code == 0, $"articulations: the engine schedules keyswitches, controllers and programs block by block — map order, one switch per phrase, offsets and lead, momentary holds, chase on seek and loop wrap, seam releases, delivery ahead of the note on its channel (failed check: {code})");
        }

        // A Legato note with track −100 ms and articulation −150 ms sounds 250 ms early, at 120 and 60 BPM.
        foreach (double bpm in new[] { 120.0, 60.0 })
        {
            int plain = OnsetWithMap(bpm, trackMs: 0, articulationMs: 0);
            int moved = OnsetWithMap(bpm, trackMs: -100, articulationMs: -150);
            int want = Rate / 4;   // 250 ms = 12000 samples
            yield return (plain > 0 && moved > 0 && Math.Abs((plain - moved) - want) <= 64,
                $"articulations: at {bpm:0} BPM, track −100 ms + Legato −150 ms plays the note 250 ms early ({plain - moved} samples, want {want})");
        }

        // Session slots (T049): the same offset moves a slot's note, the slot's clock untouched.
        int slot0 = OnsetInSlot(0), slotEarly = OnsetInSlot(-100), slotLate = OnsetInSlot(100);
        yield return (slot0 > 0 && slotEarly > 0 && slotLate > 0
                      && Math.Abs((slot0 - slotEarly) - Rate / 10) <= 64 && Math.Abs((slotLate - slot0) - Rate / 10) <= 64,
            $"articulations: a Session slot's note moves with the track offset (−100 ms: {slot0 - slotEarly}, +100 ms: {slotLate - slot0} samples, want {Rate / 10})");

        // A short loop with a large offset: +1500 ms on a 500 ms loop moves each pass's note three
        // passes on. It must still sound, 1.5 s after launch, not be lost between passes.
        int short0 = OnsetInShortSlot(0), shortLate = OnsetInShortSlot(1500);
        yield return (short0 >= 0 && shortLate > 0 && Math.Abs((shortLate - short0) - Rate * 3 / 2) <= 64,
            $"articulations: a +1500 ms offset on a 500 ms Session loop plays the note 1.5 s after launch ({shortLate - short0} samples, want {Rate * 3 / 2})");
        int tiny0 = OnsetInShortSlot(0, 0.0625), tinyLate = OnsetInShortSlot(1500, 0.0625);
        yield return (tiny0 >= 0 && tinyLate > 0 && Math.Abs((tinyLate - tiny0) - Rate * 3 / 2) <= 64,
            $"articulations: a +1500 ms offset survives 48 passes of a 31.25 ms Session loop ({tinyLate - tiny0} samples, want {Rate * 3 / 2})");
    }

    /// <summary>Where a Session slot's note on beat 1 starts sounding after the slot is launched, with a
    /// track MIDI offset (T049).</summary>
    private static int OnsetInSlot(double trackMs)
    {
        using var e = new NotaEngine();
        e.SetBpm(120);
        e.SetLaunchQuant(0.0);
        int t = e.AddInstrumentTrack();
        e.SetTrackBuiltinInstrument(t, 0);
        e.AddSessionMidiClip(t, 0, 4.0);
        e.SetSessionNotes(t, 0, new[] { new NotaNote(57, 1.0, 1.0, 0.9f) });
        e.SetTrackMidiOffsetMs(t, trackMs);
        Render(e, 2);
        e.StopTransport(); e.Seek(0); e.Play();
        e.LaunchSlot(t, 0);
        return Onset(Render(e, 94));   // ~1 s: beat 1 is at 0.5 s
    }

    /// <summary>Where a one-beat Session slot's note on beat 0 first sounds after launch, with a track
    /// offset that can move it several passes (a 500 ms loop at 120 BPM).</summary>
    private static int OnsetInShortSlot(double trackMs, double loopBeats = 1.0)
    {
        using var e = new NotaEngine();
        e.SetBpm(120);
        e.SetLaunchQuant(0.0);
        int t = e.AddInstrumentTrack();
        e.SetTrackBuiltinInstrument(t, 0);
        e.AddSessionMidiClip(t, 0, loopBeats);
        e.SetSessionNotes(t, 0, new[] { new NotaNote(57, 0.0, loopBeats / 4, 0.9f) });
        e.SetTrackMidiOffsetMs(t, trackMs);
        Render(e, 2);
        e.StopTransport(); e.Seek(0); e.Play();
        e.LaunchSlot(t, 0);
        return Onset(Render(e, 200));   // ~2.1 s
    }

    /// <summary>Where a note on beat 2 with articulation 2 starts sounding (built-in synth: it gets
    /// no keyswitches, only the timing), with the track and the articulation offset given.</summary>
    private static int OnsetWithMap(double bpm, double trackMs, double articulationMs)
    {
        using var e = new NotaEngine();
        e.SetBpm(bpm);
        int t = e.AddInstrumentTrack();
        e.SetTrackBuiltinInstrument(t, 0);
        int c = e.AddMidiClip(t, 0, 8);
        e.SetClipNotes(t, c, new[] { new NotaNote(57, 2.0, 1.0, 0.9f) { ArticulationId = 2 } });
        var map = new Nota.Application.Articulations.ArticulationMap
        {
            Name = "Timing",
            Articulations =
            {
                new Nota.Application.Articulations.Articulation { Id = 1, Name = "Long" },
                new Nota.Application.Articulations.Articulation { Id = 2, Name = "Legato", NoteOffsetMs = articulationMs, TriggerLeadMs = 30 },
            },
        };
        Nota.Application.Articulations.ArticulationMapAssignment.Assign(e, t, map);
        e.SetTrackMidiOffsetMs(t, trackMs);
        Render(e, 2);
        e.StopTransport(); e.Seek(0); e.Play();
        double seconds = 2.0 * 60.0 / bpm + 0.6;   // past beat 2 with room
        return Onset(Render(e, (int)(seconds * Rate / Block) + 1));
    }

    // Regression (owner report, 2026-11-09): an articulation-only edit in the piano roll never reached
    // the engine because the roll's "did this clip change?" test compared fields by hand and skipped
    // the articulation. NotaNote.Same is that test now; it must notice a change to every field.
    private static IEnumerable<(bool ok, string label)> NoteEquality()
    {
        var baseNote = new NotaNote(60, 1.0, 2.0, 0.5f) { ExprId = 3, ArticulationId = 4 };
        var fields = typeof(NotaNote).GetFields(System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Instance);
        var missed = new List<string>();
        foreach (var f in fields)
        {
            object boxed = baseNote;
            object? v = f.GetValue(boxed);
            // Each arm boxed as object: a switch expression would otherwise widen them all to double.
            object changed = v switch
            {
                int i => (object)(i + 1),
                double d => (object)(d + 0.5),
                float s => (object)(s * 0.5f),
                _ => throw new InvalidOperationException($"NotaNote.{f.Name}: add its type to this test"),
            };
            f.SetValue(boxed, changed);
            if (NotaNote.Same(baseNote, (NotaNote)boxed)) missed.Add(f.Name);
        }
        yield return (fields.Length >= 6 && missed.Count == 0,
            $"articulations: NotaNote.Same notices a change to every field ({fields.Length} fields{(missed.Count > 0 ? "; missed: " + string.Join(", ", missed) : "")})");
        yield return (NotaNote.Same(baseNote, baseNote with { }), "articulations: NotaNote.Same holds for an unchanged copy");
    }

    // T045 / FR-013: a note's articulation survives every clip and note operation that keeps the note.
    private static IEnumerable<(bool ok, string label)> EditsKeepArticulations()
    {
        // The articulation of each note, by (pitch, absolute start).
        static Dictionary<(int, double), int> Arts(NotaEngine e, int t)
        {
            var d = new Dictionary<(int, double), int>();
            for (int c = 0; e.TryGetClipInfo(t, c, out var info); c++)
                if (info.IsMidi)
                    foreach (var n in e.GetClipNotes(t, c)) d[(n.Pitch, Math.Round(info.StartBeat + n.StartBeat, 6))] = n.ArticulationId;
            return d;
        }
        var notes = new[]
        {
            new NotaNote(60, 0.0, 1.0, 0.8f) { ArticulationId = 1 },
            new NotaNote(64, 0.0, 1.0, 0.8f) { ArticulationId = 2 },   // a chord, two articulations
            new NotaNote(67, 2.0, 1.0, 0.8f) { ArticulationId = 3 },
        };

        using (var e = new NotaEngine())
        {
            int t = e.AddInstrumentTrack();
            int c = e.AddMidiClip(t, 0, 4);
            e.SetClipNotes(t, c, notes);
            int dup = e.DuplicateClip(t, c);   // lands at beat 4
            var a = Arts(e, t);
            yield return (dup >= 0 && a[(60, 4.0)] == 1 && a[(64, 4.0)] == 2 && a[(67, 6.0)] == 3,
                "articulations: duplicating a clip keeps every note's articulation");
            int right = e.SplitClip(t, c, 2.0);
            a = Arts(e, t);
            yield return (right >= 0 && a[(60, 0.0)] == 1 && a[(64, 0.0)] == 2 && a[(67, 2.0)] == 3,
                "articulations: splitting a clip keeps the articulations on both sides");
            e.TrimClip(t, c, 0.0, 1.5);
            yield return (Arts(e, t)[(64, 0.0)] == 2, "articulations: trimming a clip keeps the articulations of the notes left in it");
            // The split put its right half after the original, so find the duplicate (at beat 4) by place.
            int dupNow = -1;
            for (int k = 0; e.TryGetClipInfo(t, k, out var ci); k++) if (ci.IsMidi && ci.StartBeat == 4.0) dupNow = k;
            e.CopyClip(t, dupNow);
            int pasted = e.PasteClip(t, 16.0);
            a = Arts(e, t);
            yield return (pasted >= 0 && a.Where(kv => kv.Key.Item2 >= 16).Select(kv => kv.Value).OrderBy(x => x).SequenceEqual(new[] { 1, 2, 3 }),
                "articulations: copying and pasting a clip keeps the articulations");
        }
        using (var e = new NotaEngine())
        {
            int t = e.AddInstrumentTrack();
            int c1 = e.AddMidiClip(t, 0, 2), c2 = e.AddMidiClip(t, 2, 2);
            e.SetClipNotes(t, c1, notes[..2]);
            e.SetClipNotes(t, c2, new[] { new NotaNote(67, 0.0, 1.0, 0.8f) { ArticulationId = 3 } });
            bool merged = e.ConsolidateRange(new[] { t }, 0, 4);
            var a = Arts(e, t);
            yield return (merged && a[(60, 0.0)] == 1 && a[(64, 0.0)] == 2 && a[(67, 2.0)] == 3,
                "articulations: consolidating clips into one keeps every note's articulation");

            e.AddSessionMidiClip(t, 0, 4.0);
            e.SetSessionNotes(t, 0, notes);
            var back = e.GetSessionNotes(t, 0);
            int moved = e.SessionSlotToArrangement(t, 0, 8.0);
            a = Arts(e, t);
            yield return (back.Select(n => n.ArticulationId).OrderBy(x => x).SequenceEqual(new[] { 1, 2, 3 })
                          && moved >= 0 && a[(60, 8.0)] == 1 && a[(64, 8.0)] == 2 && a[(67, 10.0)] == 3,
                "articulations: a Session slot keeps its notes' articulations, and so does moving it to the arrangement");
        }

        // The piano roll's own edits run through ClipSet (multi-clip split / merge) and NoteOverwrite.
        var set = new Nota.Application.Editing.ClipSet(new[]
        {
            new Nota.Application.Editing.OpenClip(1, 0, 0.0, 4.0), new Nota.Application.Editing.OpenClip(1, 1, 4.0, 4.0),
        }, 1, 0);
        var editor = new List<NotaNote> { notes[0], notes[1] with { StartBeat = 4.5 } };
        var owners = new List<int> { 0, 1 };
        var split = set.Split(editor, owners);
        var mergedBack = new List<NotaNote>();
        set.Merge(split, mergedBack, new List<int>());
        yield return (split.Sum(s => s.Notes.Count) == 2 && split.SelectMany(s => s.Notes).Select(n => n.ArticulationId).OrderBy(x => x).SequenceEqual(new[] { 1, 2 })
                      && mergedBack.Select(n => n.ArticulationId).OrderBy(x => x).SequenceEqual(new[] { 1, 2 }),
            "articulations: the piano roll's multi-clip split and merge keep each note's articulation");
        var resized = new List<NotaNote> { notes[0], notes[2] };
        Nota.Application.Editing.NoteOverwrite.ResizeBy(resized, new[] { 0, 1 }, 0.5, 0.05, 8.0);
        yield return (resized[0].ArticulationId == 1 && resized[1].ArticulationId == 3 && resized[0].LengthBeats == 1.5,
            "articulations: resizing notes keeps their articulations");
    }

    public static IEnumerable<(bool ok, string label)> Run()
    {
        foreach (var r in NoteEquality()) yield return r;
        foreach (var r in EditsKeepArticulations()) yield return r;

        // ---- the note field crosses the ABI with every other field intact ----
        using (var e = new NotaEngine())
        {
            int t = e.AddInstrumentTrack();
            int c = e.AddMidiClip(t, 0, 4);
            int expr = e.CreateNoteExpression(new[] { new NotaExprPoint(NoteExpressionDim.Bend, 0f, 2f) });
            var notes = new[]
            {
                new NotaNote(60, 0.0, 1.0, 0.5f) { ArticulationId = 7 },
                new NotaNote(64, 0.0, 1.0, 0.6f) { ArticulationId = 12, ExprId = expr },   // a chord, two articulations
                new NotaNote(67, 1.5, 0.25, 0.7f),                                          // none
            };
            e.SetClipNotes(t, c, notes);
            var back = e.GetClipNotes(t, c);
            var byPitch = back.ToDictionary(n => n.Pitch);
            yield return (back.Length == 3
                          && byPitch.TryGetValue(60, out var a) && a.ArticulationId == 7 && a.StartBeat == 0.0 && a.LengthBeats == 1.0 && Math.Abs(a.Velocity - 0.5f) < 1e-6
                          && byPitch.TryGetValue(64, out var b) && b.ArticulationId == 12 && b.ExprId == expr
                          && byPitch.TryGetValue(67, out var d) && d.ArticulationId == 0 && d.StartBeat == 1.5 && d.LengthBeats == 0.25,
                "articulations: each note's articulation id crosses the C ABI with every other field intact");

            // One note's change touches only that note, and undoes in one step.
            var edited = back.ToArray();
            for (int i = 0; i < edited.Length; i++) if (edited[i].Pitch == 60) edited[i].ArticulationId = 3;
            e.SetClipNotes(t, c, edited);
            var after = e.GetClipNotes(t, c).ToDictionary(n => n.Pitch);
            yield return (after[60].ArticulationId == 3 && after[64].ArticulationId == 12 && after[67].ArticulationId == 0,
                "articulations: changing one note's articulation leaves the others alone");
            e.Undo();
            yield return (e.GetClipNotes(t, c).First(n => n.Pitch == 60).ArticulationId == 7, "articulations: undo restores a note's articulation");
            e.Redo();
            yield return (e.GetClipNotes(t, c).First(n => n.Pitch == 60).ArticulationId == 3, "articulations: redo reapplies it");

            int bad = e.GetClipNotes(t, c).Length;
            e.SetClipNotes(t, c, new[] { new NotaNote(60, 0, 1, 0.5f) { ArticulationId = -5 } });
            yield return (e.GetClipNotes(t, c).Single().ArticulationId == 0 && bad == 3, "articulations: a negative articulation id is stored as none");

            // ---- the track offset ----
            yield return (e.GetTrackMidiOffsetMs(t) == 0.0, "articulations: a new track has no MIDI offset");
            e.SetTrackMidiOffsetMs(t, -150);
            yield return (e.GetTrackMidiOffsetMs(t) == -150.0, "articulations: the track offset is stored (-150 ms)");
            e.SetTrackMidiOffsetMs(t, 5000);
            yield return (e.GetTrackMidiOffsetMs(t) == 2000.0, "articulations: the track offset is clamped to +2000 ms");
            e.SetTrackMidiOffsetMs(t, double.NaN);
            yield return (e.GetTrackMidiOffsetMs(t) == 0.0, "articulations: a NaN offset is stored as 0");
            e.SetTrackMidiOffsetMs(t, -80);
            int dup = e.DuplicateTrack(t);
            yield return (dup > 0 && e.GetTrackMidiOffsetMs(dup) == -80.0, "articulations: a duplicated track keeps its MIDI offset");

            // T051: the offset is one undo step; setting the same value is none.
            e.ClearUndoHistory();
            e.SetTrackMidiOffsetMs(t, -150);
            e.SetTrackMidiOffsetMs(t, -150);
            e.Undo();
            bool undone = e.GetTrackMidiOffsetMs(t) == -80.0 && !e.CanUndo;
            e.Redo();
            yield return (undone && e.GetTrackMidiOffsetMs(t) == -150.0,
                "articulations: a track offset change is one undo step (undo −150 → −80, redo back); the same value again adds none");
            yield return (e.GetTrackMidiOffsetMs(9999) == 0.0, "articulations: no such track reads offset 0");
        }

        // ---- the offset moves playback, not the notes ----
        int at0 = OnsetWithOffset(0), early = OnsetWithOffset(-100), late = OnsetWithOffset(100);
        int ms100 = Rate / 10;   // 4800 samples
        yield return (at0 > 0 && Math.Abs(at0 - 24000) < 256, $"articulations: with no offset the note sounds on its beat (onset {at0}, beat at 24000)");
        yield return (at0 > 0 && early > 0 && Math.Abs((at0 - early) - ms100) <= 64,
            $"articulations: a -100 ms track offset plays the note 100 ms early ({at0 - early} samples, want {ms100})");
        yield return (at0 > 0 && late > 0 && Math.Abs((late - at0) - ms100) <= 64,
            $"articulations: a +100 ms track offset plays the note 100 ms late ({late - at0} samples, want {ms100})");

        // ---- save and reopen; old projects ----
        string bundle = Path.Combine(Path.GetTempPath(), "nota-art-" + Guid.NewGuid().ToString("N") + ".nota");
        try
        {
            using var e = new NotaEngine();
            int t = e.AddInstrumentTrack();
            int plain = e.AddInstrumentTrack();
            int c = e.AddMidiClip(t, 0, 4);
            e.SetClipNotes(t, c, new[] { new NotaNote(60, 0, 1, 0.8f) { ArticulationId = 5 }, new NotaNote(62, 1, 1, 0.8f) });
            e.SetTrackMidiOffsetMs(t, -120);
            var doc = ProjectService.Capture(e, new TransportState(120.0, 1.0, false, false), new List<string>());
            var savedTrack = doc.Tracks.FirstOrDefault(d => d.MidiOffsetMs is not null);
            yield return (savedTrack?.MidiOffsetMs == -120.0 && doc.Tracks.Count(d => d.MidiOffsetMs is not null) == 1,
                "articulations: only the track with an offset writes one");
            ProjectService.Save(doc, bundle, e);

            using var e2 = new NotaEngine();
            ProjectService.Apply(ProjectService.Load(bundle), e2, bundle);
            int lt = -1, lplain = -1;
            for (int i = 0; i < e2.TrackCount; i++)
                if (e2.TryGetTrackInfo(i, out var ti) && ti.IsInstrument)
                {
                    if (ti.ClipCount > 0) lt = ti.Id; else lplain = ti.Id;
                }
            var ln = lt > 0 ? e2.GetClipNotes(lt, 0).ToDictionary(n => n.Pitch) : new Dictionary<int, NotaNote>();
            yield return (lt > 0 && e2.GetTrackMidiOffsetMs(lt) == -120.0 && lplain > 0 && e2.GetTrackMidiOffsetMs(lplain) == 0.0,
                "articulations: the track offset survives saving and reopening");
            yield return (ln.Count == 2 && ln[60].ArticulationId == 5 && ln[62].ArticulationId == 0,
                "articulations: each note's articulation survives saving and reopening");
        }
        finally
        {
            try { if (Directory.Exists(bundle)) Directory.Delete(bundle, recursive: true); } catch (IOException) { }
        }

        foreach (var r in ClipTools()) yield return r;
        foreach (var r in MapOnTrack()) yield return r;
        foreach (var r in Playback()) yield return r;

        var old = ProjectMigrations.Migrate(new JsonObject { ["formatVersion"] = 29 });
        yield return (old["formatVersion"]?.GetValue<int>() == ProjectService.CurrentFormatVersion && ProjectService.CurrentFormatVersion >= 30
                      && new TrackDto().MidiOffsetMs is null && new NoteDto().Articulation is null && new NoteDto().ToNote().ArticulationId == 0,
            "articulations: a v29 project migrates past v30 with no offsets and no articulations");
    }
}