fix(importer): apply MusicXML dynamics per part and show them only where written

Dynamics were kept as one importer-wide state assigned to the next created
beat, leaking across staves and parts. Markings are now placed by position,
apply to all staves of their part for playback like MuseScore and Dorico do,
and are drawn only on the staff and voice they are written for via the new
Beat.showDynamics.

Fixes #2979

Author: Danielku15

packages/alphatab/src/generated/model/BeatCloner.ts

@@ -66,6 +66,7 @@ export class BeatCloner {
         clone.overrideDisplayDuration = original.overrideDisplayDuration;
         clone.golpe = original.golpe;
         clone.dynamics = original.dynamics;
+        clone.showDynamics = original.showDynamics;
         clone.invertBeamDirection = original.invertBeamDirection;
         clone.preferredBeamDirection = original.preferredBeamDirection;
         clone.isEffectSlurOrigin = original.isEffectSlurOrigin;

packages/alphatab/src/generated/model/BeatSerializer.ts

@@ -94,6 +94,7 @@ export class BeatSerializer {
         o.set("overridedisplayduration", obj.overrideDisplayDuration);
         o.set("golpe", obj.golpe as number);
         o.set("dynamics", obj.dynamics as number);
+        o.set("showdynamics", obj.showDynamics);
         o.set("invertbeamdirection", obj.invertBeamDirection);
         o.set("preferredbeamdirection", obj.preferredBeamDirection as number | null);
         o.set("beamingmode", obj.beamingMode as number);
@@ -256,6 +257,9 @@ export class BeatSerializer {
             case "dynamics":
                 obj.dynamics = JsonHelper.parseEnum<DynamicValue>(v, DynamicValue)!;
                 return true;
+            case "showdynamics":
+                obj.showDynamics = v as boolean | undefined;
+                return true;
             case "invertbeamdirection":
                 obj.invertBeamDirection = v! as boolean;
                 return true;

packages/alphatab/src/importer/MusicXmlDynamics.ts

@@ -0,0 +1,216 @@
+import type { MusicXmlSpanPlacement } from '@coderline/alphatab/importer/MusicXmlSpans';
+import type { Beat } from '@coderline/alphatab/model/Beat';
+import { DynamicValue } from '@coderline/alphatab/model/DynamicValue';
+import { GraceType } from '@coderline/alphatab/model/GraceType';
+import type { Staff } from '@coderline/alphatab/model/Staff';
+import type { Track } from '@coderline/alphatab/model/Track';
+
+/**
+ * A dynamics marking written in a part.
+ * @internal
+ * @record
+ */
+export interface MusicXmlDynamicsMarking {
+    value: DynamicValue;
+    /**
+     * Where the marking is written, the offset is the part of the `<offset>` affecting the sound.
+     */
+    placement: MusicXmlSpanPlacement;
+    /**
+     * The index of the staff the marking is shown on.
+     */
+    displayStaffIndex: number;
+    /**
+     * Whether the marking is written in the `<notations>` of a note rather than as a `<direction>`.
+     */
+    isNoteAttached: boolean;
+}
+
+/**
+ * Applies the dynamics markings of a part to the model.
+ *
+ * - A marking is in effect for the beats of all staves and voices of the part starting at or after it
+ *   (e.g. a single marking for both hands of a piano). Of the markings at the same position, the one of the own staff wins.
+ * - A marking is shown once, on the first note of its staff (and voice) it is in effect for. A marking attached to a
+ *   note is not shown if it repeats the marking before it on the staff (Guitar Pro writes the dynamics on every note).
+ * @internal
+ */
+export class MusicXmlDynamicsApplier {
+    private _track: Track;
+    private _beatSequence: Map<Beat, number>;
+    private _voiceIndexOf: (staff: Staff, voice: string) => number;
+
+    /**
+     * @param beatSequence The index of every beat in document order (see {@link MusicXmlSpanPosition.sequence}).
+     * @param voiceIndexOf Resolves a raw MusicXML voice to the index of the voice on the staff, -1 if not existing.
+     */
+    public constructor(
+        track: Track,
+        beatSequence: Map<Beat, number>,
+        voiceIndexOf: (staff: Staff, voice: string) => number
+    ) {
+        this._track = track;
+        this._beatSequence = beatSequence;
+        this._voiceIndexOf = voiceIndexOf;
+    }
+
+    public apply(markings: MusicXmlDynamicsMarking[]) {
+        // of markings at the same position, the later one in the document wins
+        const sorted: MusicXmlDynamicsMarking[] = [];
+        for (const marking of markings) {
+            let index = sorted.length;
+            while (index > 0 && MusicXmlDynamicsApplier._compareMarkings(sorted[index - 1], marking) > 0) {
+                index--;
+            }
+            sorted.splice(index, 0, marking);
+        }
+
+        const shown: (Beat | null)[] = [];
+        const repeated: boolean[] = [];
+        for (let i = 0; i < sorted.length; i++) {
+            shown.push(null);
+            repeated.push(false);
+        }
+
+        for (const staff of this._track.staves) {
+            let voiceCount = 0;
+            for (const bar of staff.bars) {
+                voiceCount = Math.max(voiceCount, bar.voices.length);
+            }
+
+            for (let v = 0; v < voiceCount; v++) {
+                let next = 0;
+                let current = -1;
+                let previousNote = -1;
+                for (const bar of staff.bars) {
+                    if (v >= bar.voices.length) {
+                        continue;
+                    }
+                    for (const beat of bar.voices[v].beats) {
+                        while (next < sorted.length && this._isInEffect(sorted[next], beat)) {
+                            if (
+                                current === -1 ||
+                                !MusicXmlDynamicsApplier._keepsOwnStaff(sorted[current], sorted[next], staff.index)
+                            ) {
+                                current = next;
+                            }
+                            next++;
+                        }
+
+                        beat.dynamics = current === -1 ? DynamicValue.F : sorted[current].value;
+                        beat.showDynamics = false;
+                        if (current !== -1 && this._canShow(sorted[current], staff, v, beat)) {
+                            const best = shown[current];
+                            if (best === null || this._isBetterShown(sorted[current], beat, best!)) {
+                                shown[current] = beat;
+                                repeated[current] =
+                                    sorted[current].isNoteAttached &&
+                                    previousNote !== -1 &&
+                                    sorted[previousNote].displayStaffIndex === staff.index &&
+                                    sorted[previousNote].value === sorted[current].value;
+                            }
+                        }
+                        if (!beat.isRest && !beat.isEmpty) {
+                            previousNote = current;
+                        }
+                    }
+                }
+            }
+        }
+
+        for (let i = 0; i < shown.length; i++) {
+            if (shown[i] !== null && !repeated[i]) {
+                shown[i]!.showDynamics = true;
+            }
+        }
+    }
+
+    /**
+     * Whether the marking `current` stays in effect when the marking `next` at the same position is reached:
+     * the marking written on the staff wins over the one of another staff.
+     */
+    private static _keepsOwnStaff(
+        current: MusicXmlDynamicsMarking,
+        next: MusicXmlDynamicsMarking,
+        staffIndex: number
+    ): boolean {
+        return (
+            MusicXmlDynamicsApplier._compareStart(current, next) === 0 &&
+            current.placement.staffIndex === staffIndex &&
+            next.placement.staffIndex !== staffIndex
+        );
+    }
+
+    private _canShow(marking: MusicXmlDynamicsMarking, staff: Staff, voiceIndex: number, beat: Beat): boolean {
+        if (staff.index !== marking.displayStaffIndex || beat.isRest || beat.isEmpty) {
+            return false;
+        }
+        if (marking.placement.voice.length > 0) {
+            const markingVoice = this._voiceIndexOf(staff, marking.placement.voice);
+            return markingVoice === -1 || markingVoice === voiceIndex;
+        }
+        return true;
+    }
+
+    /**
+     * Whether the beat shows the marking rather than the beat found before. Of the first notes at the same position,
+     * the one following the marking in the document wins, otherwise the one of the lowest voice.
+     */
+    private _isBetterShown(marking: MusicXmlDynamicsMarking, beat: Beat, best: Beat): boolean {
+        const compare = MusicXmlDynamicsApplier._compare(
+            beat.voice.bar.index,
+            beat.displayStart,
+            best.voice.bar.index,
+            best.displayStart
+        );
+        if (compare !== 0) {
+            return compare < 0;
+        }
+        return this._sequenceOf(beat) === marking.placement.position.sequence;
+    }
+
+    private _isInEffect(marking: MusicXmlDynamicsMarking, beat: Beat): boolean {
+        const compare = MusicXmlDynamicsApplier._compare(
+            marking.placement.position.barIndex,
+            MusicXmlDynamicsApplier._ticks(marking),
+            beat.voice.bar.index,
+            beat.displayStart
+        );
+        if (compare !== 0) {
+            return compare < 0;
+        }
+        // beats without duration (grace notes) at the same position are ordered as in the document
+        return beat.graceType === GraceType.None || this._sequenceOf(beat) >= marking.placement.position.sequence;
+    }
+
+    private _sequenceOf(beat: Beat): number {
+        return this._beatSequence.has(beat) ? this._beatSequence.get(beat)! : -1;
+    }
+
+    /**
+     * The position the marking is in effect from. A sound offset only moves the marking before the cursor it is
+     * written at, a positive one is ignored as exporters use it to nudge markings into the note they belong to (e.g. Finale).
+     */
+    private static _ticks(marking: MusicXmlDynamicsMarking): number {
+        const position = marking.placement.position;
+        return Math.max(0, position.ticks + Math.min(0, position.offset));
+    }
+
+    private static _compareStart(a: MusicXmlDynamicsMarking, b: MusicXmlDynamicsMarking): number {
+        return MusicXmlDynamicsApplier._compare(
+            a.placement.position.barIndex,
+            MusicXmlDynamicsApplier._ticks(a),
+            b.placement.position.barIndex,
+            MusicXmlDynamicsApplier._ticks(b)
+        );
+    }
+
+    private static _compareMarkings(a: MusicXmlDynamicsMarking, b: MusicXmlDynamicsMarking): number {
+        const compare = MusicXmlDynamicsApplier._compareStart(a, b);
+        return compare !== 0 ? compare : a.placement.position.sequence - b.placement.position.sequence;
+    }
+
+    private static _compare(barIndexA: number, ticksA: number, barIndexB: number, ticksB: number): number {
+        return barIndexA !== barIndexB ? barIndexA - barIndexB : ticksA - ticksB;
+    }
+}