using System.Text.Json; using GAJ3T.MusicGen.RiffGrooveBuilder.Core.Articulations; using GAJ3T.MusicGen.RiffGrooveBuilder.Core.Composition; using static GAJ3T.MusicGen.RiffGrooveBuilder.UnitTests.Articulations.SyntheticProfiles; using MusicalComposition = GAJ3T.MusicGen.RiffGrooveBuilder.Core.Composition.Composition; namespace GAJ3T.MusicGen.RiffGrooveBuilder.UnitTests.Articulations; public sealed class ArticulationPlannerTests { private static MidiEventPlan Plan(Data profile, params MusicalNote[] notes) { var result = ArticulationPlanner.Plan(Model(notes), [profile.Build()], true); Assert.True(result.Success, string.Join("; ", result.Diagnostics)); Assert.Empty(result.Diagnostics); return result.Plan!; } private static void Fails(ArticulationPlanningResult result, string code) { Assert.False(result.Success); Assert.Null(result.Plan); Assert.Contains(result.Diagnostics, e => e.Code == code); } [Fact] public void KeyswitchLatchesSuppressRepeatsAndExplicitlyTransitionsToSustain() { var plan = Plan(Switched(), Note(articulation: Articulation.PalmMute), Note(1, articulation: Articulation.PalmMute), Note(3)); Assert.Equal(120, plan.LeadInTicks); Assert.Equal(15_360, plan.MusicalExtentTicks); Assert.Equal(15_480, plan.MusicalEndTick); Assert.Equal(15_480, plan.EndTick); var events = Assert.Single(plan.Tracks).Events; Assert.Equal(new PlannedNoteOn[] { new(0, 0, 11, 91, true), new(2880, 0, 10, 90, true) }, events.OfType().Where(e => e.IsKeyswitch)); Assert.Equal(new PlannedNoteOff[] { new(30, 0, 11, true), new(2910, 0, 10, true) }, events.OfType().Where(e => e.IsKeyswitch)); Assert.Equal(new long[] { 120, 1080, 3000 }, events.OfType().Where(e => !e.IsKeyswitch).Select(e => e.Tick)); Assert.Equal(new long[] { 1080, 2040, 3960 }, events.OfType().Where(e => !e.IsKeyswitch).Select(e => e.Tick)); AssertPairs(plan); } [Fact] public void InitialLatchedStateDoesNotEmitAnUnrequestedSwitch() { var plan = Plan(Switched(), Note()); Assert.DoesNotContain(plan.Tracks[0].Events.OfType(), e => e.IsKeyswitch); } [Theory] [InlineData(Articulation.Sustain, 10, 90)] [InlineData(Articulation.PalmMute, 11, 91)] public void UnknownReceiverSelectsOnlyFirstRequestedStateAndSuppressesRepeatedLatches( Articulation first, int pitch, int velocity) { var other = first == Articulation.Sustain ? Articulation.PalmMute : Articulation.Sustain; var model = Model(Note(articulation: first), Note(2, articulation: first), Note(4, articulation: other)); var source = JsonSerializer.Serialize(model); var data = Switched(cc: true) with { Initial = null }; var result = ArticulationPlanner.Plan(model, [data.Build()], true); Assert.True(result.Success, string.Join("; ", result.Diagnostics)); var plan = result.Plan!; var events = plan.Tracks[0].Events; Assert.Equal(120, plan.LeadInTicks); var switches = events.OfType().Where(e => e.IsKeyswitch).ToArray(); Assert.Equal(new PlannedNoteOn(0, 0, pitch, velocity, true), switches[0]); Assert.Equal(2, switches.Length); Assert.Equal(3840, switches[1].Tick); Assert.NotEqual(switches[0].Pitch, switches[1].Pitch); Assert.Equal(new long[] { 30, 3870 }, events.OfType().Where(e => e.IsKeyswitch).Select(e => e.Tick)); Assert.Equal(new long[] { 120, 2040, 3960 }, events.OfType().Where(e => !e.IsKeyswitch).Select(e => e.Tick)); Assert.Equal(new long[] { 1080, 3000, 4920 }, events.OfType().Where(e => !e.IsKeyswitch).Select(e => e.Tick)); Assert.Equal(source, JsonSerializer.Serialize(model)); AssertPairs(plan); } [Theory] [InlineData(1, Articulation.Sustain)] [InlineData(63, Articulation.Sustain)] [InlineData(64, Articulation.PalmMute)] [InlineData(127, Articulation.PalmMute)] public void VelocityOnlyPreservesDynamicsAtInclusiveLayerBoundaries(int velocity, Articulation articulation) { var plan = Plan(new Data { Rules = [Rule(max: 63), Rule(Articulation.PalmMute, min: 64)] }, Note(velocity: velocity, articulation: articulation)); Assert.Equal(0, plan.LeadInTicks); Assert.Equal(new PlannedNoteOn(0, 0, 64, velocity, false), Assert.Single(plan.Tracks[0].Events.OfType())); Assert.Equal(new PlannedNoteOff(960, 0, 64, false), Assert.Single(plan.Tracks[0].Events.OfType())); } [Theory] [InlineData(64, Articulation.Sustain)] [InlineData(63, Articulation.PalmMute)] public void VelocityLayerConflictsNeverClamp(int velocity, Articulation articulation) => Fails(ArticulationPlanner.Plan(Model(Note(velocity: velocity, articulation: articulation)), [new Data { Rules = [Rule(max: 63), Rule(Articulation.PalmMute, min: 64)] }.Build()], true), "velocity_layer_conflict"); [Fact] public void ExplicitVelocityTransformationDoesNotMutateMusicalDynamics() { var note = Note(velocity: 80, articulation: Articulation.PalmMute); var plan = Plan(new Data { Rules = [Rule(max: 63), Rule(Articulation.PalmMute, min: 64, output: 100)] }, note); Assert.Equal(100, Assert.Single(plan.Tracks[0].Events.OfType()).Velocity); Assert.Equal(80, note.Velocity); } [Fact] public void CcOnlyUsesInitialStateSuppressesRepeatsAndAppliesOnlyExplicitFinalReset() { var data = new Data { InitialControllers = [new(20, 0)], FinalControllers = [new(20, 0)], Rules = [ Rule(behavior: StateBehavior.Latched, cc: [new(20, 0)]), Rule(Articulation.PalmMute, StateBehavior.Latched, cc: [new(20, 100)]) ] }; var plan = Plan(data, Note(articulation: Articulation.PalmMute), Note(1, articulation: Articulation.PalmMute)); Assert.Equal(new PlannedControlChange[] { new(0, 0, 20, 0, true), new(0, 0, 20, 100, false), new(15_360, 0, 20, 0, true) }, plan.Tracks[0].Events.OfType()); Assert.DoesNotContain(plan.Tracks[0].Events.OfType(), e => e.IsKeyswitch); var withoutReset = Plan(data with { FinalControllers = [] }, Note(articulation: Articulation.PalmMute)); Assert.Equal(2, withoutReset.Tracks[0].Events.OfType().Count()); AssertPairs(plan); } [Fact] public void CombinedKeyswitchVelocityAndCcHaveExactValuesAndStableOrder() { var data = Switched(cc: true) with { Rules = [ Rule(behavior: StateBehavior.Latched, key: new(10, 90, 120, 30), cc: [new(20, 0)]), Rule(Articulation.PalmMute, StateBehavior.Latched, new(11, 91, 120, 30), [new(20, 100)], min: 64, output: 110) ] }; var plan = Plan(data, Note(velocity: 96, articulation: Articulation.PalmMute)); Assert.Equal(new PlannedMidiEvent[] { new PlannedControlChange(0, 0, 20, 0, true), new PlannedControlChange(0, 0, 20, 100, false), new PlannedNoteOn(0, 0, 11, 91, true), new PlannedNoteOff(30, 0, 11, true), new PlannedNoteOn(120, 0, 64, 110, false), new PlannedNoteOff(1080, 0, 64, false) }, plan.Tracks[0].Events); AssertPairs(plan); } [Fact] public void MomentaryControlsRetriggerAndRestoreInitialCcWithoutExtraSustainSwitch() { var plan = Plan(Switched(StateBehavior.Momentary, cc: true), Note(articulation: Articulation.PalmMute), Note(2, articulation: Articulation.PalmMute), Note(4)); Assert.Equal(new PlannedNoteOn[] { new(0, 0, 11, 91, true), new(1920, 0, 11, 91, true) }, plan.Tracks[0].Events.OfType().Where(e => e.IsKeyswitch)); Assert.Equal(new PlannedNoteOff[] { new(1080, 0, 11, true), new(3000, 0, 11, true) }, plan.Tracks[0].Events.OfType().Where(e => e.IsKeyswitch)); Assert.Equal(new PlannedControlChange[] { new(0, 0, 20, 0, true), new(0, 0, 20, 100, false), new(1080, 0, 20, 0, true), new(1920, 0, 20, 100, false), new(3000, 0, 20, 0, true) }, plan.Tracks[0].Events.OfType()); AssertPairs(plan); } [Fact] public void MomentaryMinimumHoldDurationExtendsFinalReleaseBeyondMusicalExtent() { var plan = Plan(Switched(StateBehavior.Momentary, duration: 2000, cc: true), Note(15, articulation: Articulation.PalmMute)); Assert.Equal(15_480, plan.MusicalEndTick); Assert.Equal(16_400, plan.EndTick); Assert.Contains(new PlannedNoteOff(16_400, 0, 11, true), plan.Tracks[0].Events); Assert.Contains(new PlannedControlChange(16_400, 0, 20, 0, true), plan.Tracks[0].Events); AssertPairs(plan); } [Fact] public void ExplicitFinalLatchedResetIncludesItsPulseTail() { var plan = Plan(Switched() with { Reset = Articulation.Sustain }, Note(15, articulation: Articulation.PalmMute)); Assert.Equal(15_510, plan.EndTick); Assert.Contains(new PlannedNoteOn(15_480, 0, 10, 90, true), plan.Tracks[0].Events); Assert.Contains(new PlannedNoteOff(15_510, 0, 10, true), plan.Tracks[0].Events); AssertPairs(plan); } [Fact] public void SameTickReleasesPrecedeResetsThenStateChangesThenMusicalNotes() { var plan = Plan(Switched(StateBehavior.Momentary, advance: 0, duration: 1, cc: true), Note(articulation: Articulation.PalmMute), Note(1, articulation: Articulation.PalmMute)); var boundary = plan.Tracks[0].Events.Where(e => e.Tick == 960).ToArray(); Assert.Equal(new[] { 0, 0, 1, 2, 2, 3 }, boundary.Select(e => e.Priority)); Assert.IsType(boundary[2]); Assert.Equal(0, ((PlannedControlChange)boundary[2]).Value); Assert.Equal(100, ((PlannedControlChange)boundary[3]).Value); AssertPairs(plan); } [Fact] public void AdjacentLatchedTransitionWithZeroAdvanceUsesNewStateAtBoundary() { var plan = Plan(Switched(advance: 0, cc: true), Note(articulation: Articulation.PalmMute), Note(1)); var boundary = plan.Tracks[0].Events.Where(e => e.Tick == 960).ToArray(); Assert.Equal(new[] { 0, 2, 2, 3 }, boundary.Select(e => e.Priority)); Assert.Equal(new PlannedControlChange(960, 0, 20, 0, false), boundary[1]); Assert.Equal(new PlannedNoteOn(960, 0, 10, 90, true), boundary[2]); } [Fact] public void DistinctVelocityLayersCanCoexistWithoutChannelWideControls() { var plan = Plan(new Data { Rules = [Rule(max: 63), Rule(Articulation.PalmMute, min: 64)] }, Note(pitch: 64, velocity: 50), Note(pitch: 65, velocity: 100, articulation: Articulation.PalmMute)); Assert.Equal(2, plan.Tracks[0].Events.OfType().Count()); AssertPairs(plan); } [Fact] public void SameLatchedStateAllowsChordAndEmitsOneSwitch() { var plan = Plan(Switched(), Note(articulation: Articulation.PalmMute), Note(pitch: 65, articulation: Articulation.PalmMute)); Assert.Single(plan.Tracks[0].Events.OfType(), e => e.IsKeyswitch); AssertPairs(plan); } [Fact] public void KeyswitchVelocityIsPartOfLatchedStateEvenWhenPitchIsIdentical() { var data = new Data { Rules = [ Rule(behavior: StateBehavior.Latched, key: new(10, 30, 0, 1)), Rule(Articulation.PalmMute, StateBehavior.Latched, new(10, 100, 0, 1)) ] }; var plan = Plan(data, Note(articulation: Articulation.PalmMute), Note(1)); Assert.Equal(new[] { 100, 30 }, plan.Tracks[0].Events.OfType() .Where(e => e.IsKeyswitch).Select(e => e.Velocity)); Fails(ArticulationPlanner.Plan(Model(Note(articulation: Articulation.PalmMute), Note(pitch: 65)), [data.Build()], true), "conflicting_articulation_state"); AssertPairs(plan); } [Fact] public void CcOnlyMomentaryRetriggersEveryNoteAndRestoresExplicitBaseline() { var data = new Data { Channel = 15, InitialControllers = [new(0, 127)], Rules = [Rule(), Rule(Articulation.PalmMute, StateBehavior.Momentary, cc: [new(0, 0)])] }; var plan = Plan(data, Note(articulation: Articulation.PalmMute), Note(1, articulation: Articulation.PalmMute), Note(2)); Assert.Equal(new PlannedControlChange[] { new(0, 15, 0, 127, true), new(0, 15, 0, 0, false), new(960, 15, 0, 127, true), new(960, 15, 0, 0, false), new(1920, 15, 0, 127, true) }, plan.Tracks[0].Events.OfType()); Assert.DoesNotContain(plan.Tracks[0].Events.OfType(), e => e.IsKeyswitch); AssertPairs(plan); } [Fact] public void DrumsWithConflictingCcStateCannotSoundTogether() { var composition = new MusicalComposition(120, new(4, 4), new(4, KeyMode.Minor), 1, [new(TrackRole.Drums, hits: [new(DrumVoice.Kick, new(0), new(1), 96), new(DrumVoice.Snare, new(0), new(1), 96)])]); var data = new Data { Role = TrackRole.Drums, Initial = null, InitialControllers = [new(20, 0)], Rules = [ Rule(behavior: StateBehavior.Latched, cc: [new(20, 0)], voice: DrumVoice.Kick, drumPitch: 50), Rule(behavior: StateBehavior.Latched, cc: [new(20, 127)], voice: DrumVoice.Snare, drumPitch: 51) ] }; Fails(ArticulationPlanner.Plan(composition, [data.Build()], true), "conflicting_articulation_state"); } [Fact] public void NonrepresentableSourceTimingFailsWithoutPartialEvents() { var note = new MusicalNote(64, new(0), new(1, 7), 96, Articulation.Sustain); Fails(ArticulationPlanner.Plan(Model(note), [new Data().Build()], true), "unrepresentable_timing"); } [Fact] public void FinalResetPulseOverflowIsCheckedAfterOtherwiseRepresentableEvents() => Fails(ArticulationPlanner.Plan(Model(Note(articulation: Articulation.PalmMute)), [(Switched(advance: 0, duration: long.MaxValue - 1000) with { Reset = Articulation.Sustain }).Build()], true), "arithmetic_overflow"); [Fact] public void FractionalTickRepresentableAdvanceAndMusicalTimingStayExact() { var note = new MusicalNote(64, new(1, 4), new(1, 4), 127, Articulation.PalmMute); var plan = Plan(Switched(advance: 1, duration: 1), note); Assert.Equal(1, plan.LeadInTicks); Assert.Contains(new PlannedNoteOn(240, 0, 11, 91, true), plan.Tracks[0].Events); Assert.Contains(new PlannedNoteOn(241, 0, 64, 127, false), plan.Tracks[0].Events); Assert.Contains(new PlannedNoteOff(481, 0, 64, false), plan.Tracks[0].Events); AssertPairs(plan); } [Fact] public void UnusedRuleDoesNotAddLeadInOrCauseHypotheticalOverflow() { var data = new Data { Rules = [ Rule(behavior: StateBehavior.Latched, key: new(10, 90, 0, 1)), Rule(Articulation.PalmMute, StateBehavior.Latched, new(11, 91, long.MaxValue, 1)) ] }; var plan = Plan(data, Note()); Assert.Equal(0, plan.LeadInTicks); Assert.Equal(new PlannedNoteOn(0, 0, 64, 96, false), Assert.Single(plan.Tracks[0].Events.OfType())); } [Theory] [InlineData(StateBehavior.Latched, 0)] [InlineData(StateBehavior.Momentary, 0)] [InlineData(StateBehavior.Latched, 120)] public void ConflictingSimultaneousArticulationsFail(StateBehavior behavior, long advance) => Fails(ArticulationPlanner.Plan(Model(Note(articulation: Articulation.PalmMute), Note(pitch: 65)), [Switched(behavior, advance).Build()], true), "conflicting_articulation_state"); [Fact] public void AdvanceIntoPreviousSustainedNoteIsNotSilentlyAccepted() => Fails(ArticulationPlanner.Plan(Model(Note(), Note(1, articulation: Articulation.PalmMute)), [Switched().Build()], true), "conflicting_articulation_state"); [Fact] public void OverlappingMomentarySameStateCannotRetriggerAmbiguously() => Fails(ArticulationPlanner.Plan(Model(Note(articulation: Articulation.PalmMute), Note(pitch: 65, articulation: Articulation.PalmMute)), [Switched(StateBehavior.Momentary).Build()], true), "conflicting_articulation_state"); [Fact] public void OverlappingSameMusicalPitchFailsEvenWithoutControls() => Fails(ArticulationPlanner.Plan(Model(Note(duration: 2), Note(1)), [new Data().Build()], true), "overlapping_midi_pitch"); [Theory] [InlineData(39)] [InlineData(101)] public void OutOfProfilePitchesFail(int pitch) => Fails(ArticulationPlanner.Plan(Model(Note(pitch: pitch)), [new Data().Build()], true), "pitch_out_of_profile_range"); [Fact] public void UnsupportedArticulationIsNotReplacedBySustain() => Fails(ArticulationPlanner.Plan(Model(Note(articulation: Articulation.PalmMute)), [new Data().Build()], true), "unsupported_articulation"); [Fact] public void ProfilesMustBeExplicitMatchedVerifiedAndUnique() { var composition = Model(Note()); Fails(ArticulationPlanner.Plan(composition, null), "missing_or_duplicate_profile"); Fails(ArticulationPlanner.Plan(composition, [null!]), "missing_profile"); Fails(ArticulationPlanner.Plan(composition, [new Data().Build()]), "unverified_profile"); Fails(ArticulationPlanner.Plan(composition, [new Data().Build(), new Data().Build()], true), "missing_or_duplicate_profile"); Fails(ArticulationPlanner.Plan(composition, [new Data { Role = TrackRole.Bass }.Build()], true), "unused_profile"); Fails(ArticulationPlanner.Plan(null, [new Data().Build()], true), "invalid_composition"); Fails(ArticulationPlanner.Plan(Model(Note(velocity: 0)), [new Data().Build()], true), "invalid_velocity"); } [Fact] public void IndependentlyControlledChannelsCannotCollide() { var composition = new MusicalComposition(120, new(4, 4), new(4, KeyMode.Minor), 1, [new(TrackRole.Lead, [Note()]), new(TrackRole.Bass, [Note(pitch: 40)])]); Fails(ArticulationPlanner.Plan(composition, [new Data().Build(), new Data { Role = TrackRole.Bass, Id = "synthetic-bass" }.Build()], true), "channel_collision"); } [Theory] [InlineData(long.MaxValue, 1, false)] [InlineData(120, long.MaxValue, true)] public void CheckedAdvanceReleaseAndFinalResetOverflowFails(long advance, long duration, bool reset) => Fails(ArticulationPlanner.Plan(Model(Note(15, articulation: Articulation.PalmMute)), [(Switched(advance: advance, duration: duration) with { Reset = reset ? Articulation.Sustain : null }).Build()], true), "arithmetic_overflow"); [Fact] public void UnmappedDrumVoiceFailsWithoutPartialPlan() { var composition = new MusicalComposition(120, new(4, 4), new(4, KeyMode.Minor), 1, [new(TrackRole.Drums, hits: [new(DrumVoice.Snare, new(0), new(1), 96)])]); var profile = new Data { Role = TrackRole.Drums, Initial = null, Rules = [Rule(voice: DrumVoice.Kick, drumPitch: 50)] }.Build(); Fails(ArticulationPlanner.Plan(composition, [profile], true), "unmapped_drum_voice"); } [Fact] public void DeterministicImmutableResultsPreserveSourceAndTrailingRests() { var source = Model(Note(articulation: Articulation.PalmMute)); var before = JsonSerializer.Serialize(source); var profile = Switched().Build(); var first = ArticulationPlanner.Plan(source, [profile], true).Plan!; var second = ArticulationPlanner.Plan(source, [profile], true).Plan!; Assert.Equal(before, JsonSerializer.Serialize(source)); Assert.Equal(JsonSerializer.Serialize(first), JsonSerializer.Serialize(second)); Assert.Equal(first.Tracks[0].Events, second.Tracks[0].Events); Assert.Equal(15_480, first.EndTick); Assert.Throws(() => ((IList)first.Tracks).Clear()); Assert.Throws(() => ((IList)first.Tracks[0].Events).Clear()); AssertPairs(first); } private static void AssertPairs(MidiEventPlan plan) { foreach (var track in plan.Tracks) { var active = new Dictionary(); Assert.Equal(track.Events.OrderBy(e => e.Tick).ThenBy(e => e.Priority), track.Events); foreach (var e in track.Events) { Assert.InRange(e.Tick, 0, plan.EndTick); Assert.InRange(e.Channel, 0, 15); if (e is PlannedNoteOn on) { Assert.InRange(on.Pitch, 0, 127); Assert.InRange(on.Velocity, 1, 127); Assert.True(active.TryAdd(on.Pitch, on.Tick)); } if (e is PlannedNoteOff off) { Assert.True(active.Remove(off.Pitch, out var start)); Assert.True(off.Tick > start); } } Assert.Empty(active); } } }