@coderline/alphatab 1.8.0 → 1.8.1

package/dist/alphaTab.core.mjs

@@ -1,5 +1,5 @@
 /*!
- * alphaTab v1.8.0 (, build 26)
+ * alphaTab v1.8.1 (, build 30)
  *
  * Copyright © 2026, Daniel Kuschny and Contributors, All rights reserved.
  *
@@ -203,9 +203,9 @@ class AlphaTabError extends Error {
  * @internal
  */
 class VersionInfo {
-    static version = '1.8.0';
-    static date = '2026-01-12T15:41:07.446Z';
-    static commit = 'b3039f03e18398df334fd99c8ec92ea94c1ebea1';
+    static version = '1.8.1';
+    static date = '2026-02-01T19:53:46.853Z';
+    static commit = '8a2102fe7ee7dcf4b50c3a4198fbb8c0d5c0fda3';
     static print(print) {
         print(`alphaTab ${VersionInfo.version}`);
         print(`commit: ${VersionInfo.commit}`);
@@ -4519,135 +4519,6 @@ class ModelUtils {
             return ModelUtils._keyTransposeTable[transpose][keySignature + 7];
         }
     }
-    /**
-     * a lookup list containing an info whether the notes within an octave
-     * need an accidental rendered. the accidental symbol is determined based on the type of key signature.
-     */
-    static _keySignatureLookup = [
-        // Flats (where the value is true, a flat accidental is required for the notes)
-        [true, true, true, true, true, true, true, true, true, true, true, true],
-        [true, true, true, true, true, false, true, true, true, true, true, true],
-        [false, true, true, true, true, false, true, true, true, true, true, true],
-        [false, true, true, true, true, false, false, false, true, true, true, true],
-        [false, false, false, true, true, false, false, false, true, true, true, true],
-        [false, false, false, true, true, false, false, false, false, false, true, true],
-        [false, false, false, false, false, false, false, false, false, false, true, true],
-        // natural
-        [false, false, false, false, false, false, false, false, false, false, false, false],
-        // sharps  (where the value is true, a flat accidental is required for the notes)
-        [false, false, false, false, false, true, true, false, false, false, false, false],
-        [true, true, false, false, false, true, true, false, false, false, false, false],
-        [true, true, false, false, false, true, true, true, true, false, false, false],
-        [true, true, true, true, false, true, true, true, true, false, false, false],
-        [true, true, true, true, false, true, true, true, true, true, true, false],
-        [true, true, true, true, true, true, true, true, true, true, true, false],
-        [true, true, true, true, true, true, true, true, true, true, true, true]
-    ];
-    /**
-     * Contains the list of notes within an octave have accidentals set.
-     * @internal
-     */
-    static accidentalNotes = [
-        false,
-        true,
-        false,
-        true,
-        false,
-        false,
-        true,
-        false,
-        true,
-        false,
-        true,
-        false
-    ];
-    /**
-     * @internal
-     */
-    static computeAccidental(keySignature, accidentalMode, noteValue, quarterBend, currentAccidental = null) {
-        const ks = keySignature;
-        const ksi = ks + 7;
-        const index = noteValue % 12;
-        const accidentalForKeySignature = ksi < 7 ? AccidentalType.Flat : AccidentalType.Sharp;
-        const hasKeySignatureAccidentalSetForNote = ModelUtils._keySignatureLookup[ksi][index];
-        const hasNoteAccidentalWithinOctave = ModelUtils.accidentalNotes[index];
-        // the general logic is like this:
-        // - we check if the key signature has an accidental defined
-        // - we calculate which accidental a note needs according to its index in the octave
-        // - if the accidental is already placed at this line, nothing needs to be done, otherwise we place it
-        // - if there should not be an accidental, but there is one in the key signature, we clear it.
-        // the exceptions are:
-        // - for quarter bends we just place the corresponding accidental
-        // - the accidental mode can enforce the accidentals for the note
-        let accidentalToSet = AccidentalType.None;
-        if (quarterBend) {
-            accidentalToSet = hasNoteAccidentalWithinOctave ? accidentalForKeySignature : AccidentalType.Natural;
-            switch (accidentalToSet) {
-                case AccidentalType.Natural:
-                    accidentalToSet = AccidentalType.NaturalQuarterNoteUp;
-                    break;
-                case AccidentalType.Sharp:
-                    accidentalToSet = AccidentalType.SharpQuarterNoteUp;
-                    break;
-                case AccidentalType.Flat:
-                    accidentalToSet = AccidentalType.FlatQuarterNoteUp;
-                    break;
-            }
-        }
-        else {
-            // define which accidental should be shown ignoring what might be set on the KS already
-            switch (accidentalMode) {
-                case NoteAccidentalMode.ForceSharp:
-                    accidentalToSet = AccidentalType.Sharp;
-                    break;
-                case NoteAccidentalMode.ForceDoubleSharp:
-                    accidentalToSet = AccidentalType.DoubleSharp;
-                    break;
-                case NoteAccidentalMode.ForceFlat:
-                    accidentalToSet = AccidentalType.Flat;
-                    break;
-                case NoteAccidentalMode.ForceDoubleFlat:
-                    accidentalToSet = AccidentalType.DoubleFlat;
-                    break;
-                default:
-                    // if note has an accidental in the octave, we place a symbol
-                    // according to the Key Signature
-                    if (hasNoteAccidentalWithinOctave) {
-                        accidentalToSet = accidentalForKeySignature;
-                    }
-                    else if (hasKeySignatureAccidentalSetForNote) {
-                        // note does not get an accidental, but KS defines one -> Naturalize
-                        accidentalToSet = AccidentalType.Natural;
-                    }
-                    break;
-            }
-            // do we need an accidental on the note?
-            if (accidentalToSet !== AccidentalType.None) {
-                // if there is no accidental on the line, and the key signature has it set already, we clear it on the note
-                if (currentAccidental != null) {
-                    if (currentAccidental === accidentalToSet) {
-                        accidentalToSet = AccidentalType.None;
-                    }
-                }
-                else if (hasKeySignatureAccidentalSetForNote && accidentalToSet === accidentalForKeySignature) {
-                    accidentalToSet = AccidentalType.None;
-                }
-            }
-            else {
-                // if we don't want an accidental, but there is already one applied, we place a naturalize accidental
-                // and clear the registration
-                if (currentAccidental !== null) {
-                    if (currentAccidental === AccidentalType.Natural) {
-                        accidentalToSet = AccidentalType.None;
-                    }
-                    else {
-                        accidentalToSet = AccidentalType.Natural;
-                    }
-                }
-            }
-        }
-        return accidentalToSet;
-    }
     /**
      * @internal
      */
@@ -4686,6 +4557,239 @@ class ModelUtils {
         }
         return systemIndex < systemsLayout.length ? systemsLayout[systemIndex] : defaultSystemsLayout;
     }
+    // diatonic accidentals
+    static _degreeSemitones = [0, 2, 4, 5, 7, 9, 11];
+    static _sharpPreferredSpellings = [
+        { degree: 0, accidentalOffset: 0 }, // C
+        { degree: 0, accidentalOffset: 1 }, // C#
+        { degree: 1, accidentalOffset: 0 }, // D
+        { degree: 1, accidentalOffset: 1 }, // D#
+        { degree: 2, accidentalOffset: 0 }, // E
+        { degree: 3, accidentalOffset: 0 }, // F
+        { degree: 3, accidentalOffset: 1 }, // F#
+        { degree: 4, accidentalOffset: 0 }, // G
+        { degree: 4, accidentalOffset: 1 }, // G#
+        { degree: 5, accidentalOffset: 0 }, // A
+        { degree: 5, accidentalOffset: 1 }, // A#
+        { degree: 6, accidentalOffset: 0 } // B
+    ];
+    static _flatPreferredSpellings = [
+        { degree: 0, accidentalOffset: 0 }, // C
+        { degree: 1, accidentalOffset: -1 }, // Db
+        { degree: 1, accidentalOffset: 0 }, // D
+        { degree: 2, accidentalOffset: -1 }, // Eb
+        { degree: 2, accidentalOffset: 0 }, // E
+        { degree: 3, accidentalOffset: 0 }, // F
+        { degree: 4, accidentalOffset: -1 }, // Gb
+        { degree: 4, accidentalOffset: 0 }, // G
+        { degree: 5, accidentalOffset: -1 }, // Ab
+        { degree: 5, accidentalOffset: 0 }, // A
+        { degree: 6, accidentalOffset: -1 }, // Bb
+        { degree: 6, accidentalOffset: 0 } // B
+    ];
+    // 12 chromatic pitch classes with always 3 possible spellings in the
+    // accidental range of bb..##
+    static _spellingCandidates = [
+        // 0: C
+        [
+            { degree: 0, accidentalOffset: 0 }, // C
+            { degree: 1, accidentalOffset: -2 }, // Dbb
+            { degree: 6, accidentalOffset: 1 } // B#
+        ],
+        // 1: C#/Db
+        [
+            { degree: 0, accidentalOffset: 1 }, // C#
+            { degree: 1, accidentalOffset: -1 }, // Db
+            { degree: 6, accidentalOffset: 2 } // B##
+        ],
+        // 2: D
+        [
+            { degree: 1, accidentalOffset: 0 }, // D
+            { degree: 0, accidentalOffset: 2 }, // C##
+            { degree: 2, accidentalOffset: -2 } // Ebb
+        ],
+        // 3: D#/Eb
+        [
+            { degree: 1, accidentalOffset: 1 }, // D#
+            { degree: 2, accidentalOffset: -1 }, // Eb
+            { degree: 3, accidentalOffset: -2 } // Fbb
+        ],
+        // 4: E
+        [
+            { degree: 2, accidentalOffset: 0 }, // E
+            { degree: 1, accidentalOffset: 2 }, // D##
+            { degree: 3, accidentalOffset: -1 } // Fb
+        ],
+        // 5: F
+        [
+            { degree: 3, accidentalOffset: 0 }, // F
+            { degree: 2, accidentalOffset: 1 }, // E#
+            { degree: 4, accidentalOffset: -2 } // Gbb
+        ],
+        // 6: F#/Gb
+        [
+            { degree: 3, accidentalOffset: 1 }, // F#
+            { degree: 4, accidentalOffset: -1 }, // Gb
+            { degree: 2, accidentalOffset: 2 } // E##
+        ],
+        // 7: G
+        [
+            { degree: 4, accidentalOffset: 0 }, // G
+            { degree: 3, accidentalOffset: 2 }, // F##
+            { degree: 5, accidentalOffset: -2 } // Abb
+        ],
+        // 8: G#/Ab
+        [
+            { degree: 4, accidentalOffset: 1 }, // G#
+            { degree: 5, accidentalOffset: -1 } // Ab
+        ],
+        // 9: A
+        [
+            { degree: 5, accidentalOffset: 0 }, // A
+            { degree: 4, accidentalOffset: 2 }, // G##
+            { degree: 6, accidentalOffset: -2 } // Bbb
+        ],
+        // 10: A#/Bb
+        [
+            { degree: 5, accidentalOffset: 1 }, // A#
+            { degree: 6, accidentalOffset: -1 }, // Bb
+            { degree: 0, accidentalOffset: -2 } // Cbb
+        ],
+        // 11: B
+        [
+            { degree: 6, accidentalOffset: 0 }, // B
+            { degree: 5, accidentalOffset: 2 }, // A##
+            { degree: 0, accidentalOffset: -1 } // Cb
+        ]
+    ];
+    static _sharpKeySignatureOrder = [3, 0, 4, 1, 5, 2, 6]; // F C G D A E B
+    static _flatKeySignatureOrder = [6, 2, 5, 1, 4, 0, 3]; // B E A D G C F
+    static _keySignatureAccidentalByDegree = ModelUtils._buildKeySignatureAccidentalByDegree();
+    static _accidentalOffsetToType = new Map([
+        [-2, AccidentalType.DoubleFlat],
+        [-1, AccidentalType.Flat],
+        [0, AccidentalType.Natural],
+        [1, AccidentalType.Sharp],
+        [2, AccidentalType.DoubleSharp]
+    ]);
+    static _forcedAccidentalOffsetByMode = new Map([
+        [NoteAccidentalMode.ForceSharp, 1],
+        [NoteAccidentalMode.ForceDoubleSharp, 2],
+        [NoteAccidentalMode.ForceFlat, -1],
+        [NoteAccidentalMode.ForceDoubleFlat, -2],
+        [NoteAccidentalMode.ForceNatural, 0],
+        [NoteAccidentalMode.ForceNone, 0],
+        [NoteAccidentalMode.Default, Number.NaN]
+    ]);
+    static _buildKeySignatureAccidentalByDegree() {
+        const lookup = [];
+        for (let ks = -7; ks <= 7; ks++) {
+            const row = [0, 0, 0, 0, 0, 0, 0];
+            if (ks > 0) {
+                for (let i = 0; i < ks; i++) {
+                    row[ModelUtils._sharpKeySignatureOrder[i]] = 1;
+                }
+            }
+            else if (ks < 0) {
+                for (let i = 0; i < -ks; i++) {
+                    row[ModelUtils._flatKeySignatureOrder[i]] = -1;
+                }
+            }
+            lookup.push(row);
+        }
+        return lookup;
+    }
+    static getKeySignatureAccidentalOffset(keySignature, degree) {
+        return ModelUtils._keySignatureAccidentalByDegree[keySignature + 7][degree];
+    }
+    static resolveSpelling(keySignature, noteValue, accidentalMode) {
+        const chroma = ModelUtils.flooredDivision(noteValue, 12);
+        const preferred = ModelUtils._getPreferredSpellingForKeySignature(keySignature, chroma);
+        const desiredOffset = ModelUtils._forcedAccidentalOffsetByMode.has(accidentalMode)
+            ? ModelUtils._forcedAccidentalOffsetByMode.get(accidentalMode)
+            : Number.NaN;
+        let spelling = preferred;
+        if (!Number.isNaN(desiredOffset)) {
+            const candidates = ModelUtils._spellingCandidates[chroma];
+            const exact = candidates.find(c => c.accidentalOffset === desiredOffset);
+            if (exact) {
+                spelling = exact;
+            }
+        }
+        const baseSemitone = ModelUtils._degreeSemitones[spelling.degree] + spelling.accidentalOffset;
+        const octave = Math.floor((noteValue - baseSemitone) / 12) - 1;
+        return {
+            degree: spelling.degree,
+            accidentalOffset: spelling.accidentalOffset,
+            chroma,
+            octave
+        };
+    }
+    static computeAccidental(keySignature, accidentalMode, noteValue, quarterBend, currentAccidentalOffset = null) {
+        const spelling = ModelUtils.resolveSpelling(keySignature, noteValue, accidentalMode);
+        return ModelUtils.computeAccidentalForSpelling(keySignature, accidentalMode, spelling, quarterBend, currentAccidentalOffset);
+    }
+    static computeAccidentalForSpelling(keySignature, accidentalMode, spelling, quarterBend, currentAccidentalOffset = null) {
+        if (accidentalMode === NoteAccidentalMode.ForceNone) {
+            return AccidentalType.None;
+        }
+        if (quarterBend) {
+            if (spelling.accidentalOffset > 0) {
+                return AccidentalType.SharpQuarterNoteUp;
+            }
+            if (spelling.accidentalOffset < 0) {
+                return AccidentalType.FlatQuarterNoteUp;
+            }
+            return AccidentalType.NaturalQuarterNoteUp;
+        }
+        const desiredOffset = spelling.accidentalOffset;
+        const ksOffset = ModelUtils.getKeySignatureAccidentalOffset(keySignature, spelling.degree);
+        // already active in bar -> no accidental needed
+        if (currentAccidentalOffset === desiredOffset) {
+            return AccidentalType.None;
+        }
+        // key signature already defines the accidental and no explicit accidental is active
+        if (currentAccidentalOffset == null && desiredOffset === ksOffset) {
+            return AccidentalType.None;
+        }
+        return ModelUtils.accidentalOffsetToType(desiredOffset);
+    }
+    static accidentalOffsetToType(offset) {
+        return ModelUtils._accidentalOffsetToType.has(offset)
+            ? ModelUtils._accidentalOffsetToType.get(offset)
+            : AccidentalType.None;
+    }
+    static _getPreferredSpellingForKeySignature(keySignature, chroma) {
+        const candidates = ModelUtils._spellingCandidates[chroma];
+        const ksMatch = candidates.find(c => ModelUtils.getKeySignatureAccidentalOffset(keySignature, c.degree) === c.accidentalOffset);
+        if (ksMatch) {
+            return ksMatch;
+        }
+        const preferFlat = ModelUtils.keySignatureIsFlat(keySignature);
+        return preferFlat ? ModelUtils._flatPreferredSpellings[chroma] : ModelUtils._sharpPreferredSpellings[chroma];
+    }
+    static _majorKeySignatureTonicDegrees = [
+        // Flats: Cb, Gb, Db, Ab, Eb, Bb, F
+        0, 4, 1, 5, 2, 6, 3,
+        // Natural: C
+        0,
+        // Sharps: G, D, A, E, B, F#, C#
+        4, 1, 5, 2, 6, 3, 0
+    ];
+    static _minorKeySignatureTonicDegrees = [
+        // Flats: Ab, Eb, Bb, F, C, G, D
+        5, 2, 6, 3, 0, 4, 1,
+        // Natural: A
+        5,
+        // Sharps: E, B, F#, C#, G#, D#, A#
+        2, 6, 3, 0, 4, 1, 5
+    ];
+    static getKeySignatureTonicDegree(keySignature, keySignatureType) {
+        const ksi = keySignature + 7;
+        return keySignatureType === KeySignatureType.Minor
+            ? ModelUtils._minorKeySignatureTonicDegrees[ksi]
+            : ModelUtils._majorKeySignatureTonicDegrees[ksi];
+    }
 }
 
 /**
@@ -5396,7 +5500,8 @@ class PercussionMapper {
                 }
             }
         }
-        return 'unknown';
+        // unknown combination, should not happen, fallback to some default value (Snare hit)
+        return 'Snare (hit)';
     }
     static getArticulation(n) {
         const articulationIndex = n.percussionArticulation;
@@ -15572,7 +15677,11 @@ class AlphaTex1LanguageHandler {
             const slurId = `s${note.slurOrigin.id}`;
             Atnf.prop(properties, 'slur', Atnf.identValue(slurId));
         }
-        if (note.accidentalMode !== NoteAccidentalMode.Default) {
+        // NOTE: it would be better to check via accidentalhelper what accidentals we really need to force
+        const skipAccidental = note.accidentalMode === NoteAccidentalMode.Default ||
+            (note.beat.voice.bar.keySignature === KeySignature.C &&
+                note.accidentalMode === NoteAccidentalMode.ForceNatural);
+        if (!skipAccidental) {
             Atnf.prop(properties, 'acc', Atnf.identValue(ModelUtils.reverseAccidentalModeMapping.get(note.accidentalMode)));
         }
         switch (note.ornament) {
@@ -19537,6 +19646,24 @@ var Direction;
  */
 class Gp3To5Importer extends ScoreImporter {
     static _versionString = 'FICHIER GUITAR PRO ';
+    // NOTE: General Midi only defines percussion instruments from 35-81
+    // Guitar Pro 5 allowed GS extensions (27-34 and 82-87)
+    // GP7-8 do not have all these definitions anymore, this lookup ensures some fallback 
+    // (even if they are not correct)
+    // we can support this properly in future when we allow custom alphaTex articulation definitions
+    // then we don't need to rely on GP specifics anymore but handle things on export/import
+    static _gp5PercussionInstrumentMap = new Map([
+        // High Q -> GS "High Q / Filter Snap"
+        [27, 42],
+        // Slap
+        [28, 60],
+        // Scratch Push
+        [29, 29],
+        // Scratch Pull
+        [30, 30],
+        // Square Click
+        [32, 31]
+    ]);
     _versionNumber = 0;
     _score;
     _globalTripletFeel = TripletFeel.NoTripletFeel;
@@ -19883,9 +20010,9 @@ class Gp3To5Importer extends ScoreImporter {
         }
     }
     /**
-     * Guitar Pro 3-6 changes to a bass clef if any string tuning is below B2;
+     * Guitar Pro 3-6 changes to a bass clef if any string tuning is below B1
      */
-    static _bassClefTuningThreshold = ModelUtils.parseTuning('B2').realValue;
+    static _bassClefTuningThreshold = ModelUtils.parseTuning('B1').realValue;
     readTrack() {
         const newTrack = new Track();
         newTrack.ensureStaveCount(1);
@@ -20606,7 +20733,9 @@ class Gp3To5Importer extends ScoreImporter {
             this.readNoteEffects(track, voice, beat, newNote);
         }
         if (bar.staff.isPercussion) {
-            newNote.percussionArticulation = newNote.fret;
+            newNote.percussionArticulation = Gp3To5Importer._gp5PercussionInstrumentMap.has(newNote.fret)
+                ? Gp3To5Importer._gp5PercussionInstrumentMap.get(newNote.fret)
+                : newNote.fret;
             newNote.string = -1;
             newNote.fret = -1;
         }
@@ -23858,6 +23987,9 @@ class GpifParser {
                 switch (c.localName) {
                     case 'Accidental':
                         switch (c.innerText) {
+                            case '':
+                                note.accidentalMode = NoteAccidentalMode.ForceNatural;
+                                break;
                             case 'x':
                                 note.accidentalMode = NoteAccidentalMode.ForceDoubleSharp;
                                 break;
@@ -24896,13 +25028,9 @@ class AccidentalHelper {
      */
     static _octaveSteps = [38, 32, 30, 26, 38];
     /**
-     * The step offsets of the notes within an octave in case of for sharp keysignatures
-     */
-    static sharpNoteSteps = [0, 0, 1, 1, 2, 3, 3, 4, 4, 5, 5, 6];
-    /**
-     * The step offsets of the notes within an octave in case of for flat keysignatures
+     * Diatonic step offsets within an octave.
      */
-    static flatNoteSteps = [0, 1, 1, 2, 2, 3, 4, 4, 5, 5, 6, 6];
+    static _diatonicSteps = [0, 1, 2, 3, 4, 5, 6];
     _registeredAccidentals = new Map();
     _appliedScoreSteps = new Map();
     _appliedScoreStepsByValue = new Map();
@@ -24934,23 +25062,7 @@ class AccidentalHelper {
         return PercussionMapper.getArticulation(note)?.staffLine ?? 0;
     }
     static getNoteValue(note) {
-        let noteValue = note.displayValue;
-        // adjust note height according to accidentals enforced
-        switch (note.accidentalMode) {
-            case NoteAccidentalMode.ForceDoubleFlat:
-                noteValue += 2;
-                break;
-            case NoteAccidentalMode.ForceDoubleSharp:
-                noteValue -= 2;
-                break;
-            case NoteAccidentalMode.ForceFlat:
-                noteValue += 1;
-                break;
-            case NoteAccidentalMode.ForceSharp:
-                noteValue -= 1;
-                break;
-        }
-        return noteValue;
+        return note.displayValue;
     }
     /**
      * Calculates the accidental for the given note and assignes the value to it.
@@ -24982,7 +25094,8 @@ class AccidentalHelper {
             steps = AccidentalHelper.getPercussionSteps(note);
         }
         else {
-            steps = AccidentalHelper.calculateNoteSteps(bar.keySignature, bar.clef, noteValue);
+            const spelling = ModelUtils.resolveSpelling(bar.keySignature, noteValue, note.accidentalMode);
+            steps = AccidentalHelper.calculateNoteSteps(bar.clef, spelling);
         }
         return steps;
     }
@@ -24995,11 +25108,12 @@ class AccidentalHelper {
         }
         else {
             const accidentalMode = note ? note.accidentalMode : NoteAccidentalMode.Default;
-            steps = AccidentalHelper.calculateNoteSteps(this._bar.keySignature, this._bar.clef, noteValue);
-            const currentAccidental = this._registeredAccidentals.has(steps)
+            const spelling = ModelUtils.resolveSpelling(this._bar.keySignature, noteValue, accidentalMode);
+            steps = AccidentalHelper.calculateNoteSteps(this._bar.clef, spelling);
+            const currentAccidentalOffset = this._registeredAccidentals.has(steps)
                 ? this._registeredAccidentals.get(steps)
                 : null;
-            accidentalToSet = ModelUtils.computeAccidental(this._bar.keySignature, accidentalMode, noteValue, quarterBend, currentAccidental);
+            accidentalToSet = ModelUtils.computeAccidentalForSpelling(this._bar.keySignature, accidentalMode, spelling, quarterBend, currentAccidentalOffset);
             let skipAccidental = false;
             switch (accidentalToSet) {
                 case AccidentalType.NaturalQuarterNoteUp:
@@ -25024,14 +25138,12 @@ class AccidentalHelper {
                     if (skipAccidental) {
                         accidentalToSet = AccidentalType.None;
                     }
-                    else {
-                        // do we need an accidental on the note?
-                        if (accidentalToSet !== AccidentalType.None) {
-                            this._registeredAccidentals.set(steps, accidentalToSet);
-                        }
-                    }
                     break;
             }
+            const shouldRegister = !quarterBend && accidentalToSet !== AccidentalType.None;
+            if (shouldRegister) {
+                this._registeredAccidentals.set(steps, spelling.accidentalOffset);
+            }
         }
         if (note) {
             this._appliedScoreSteps.set(note.id, steps);
@@ -25083,21 +25195,14 @@ class AccidentalHelper {
     getMinStepsNote(b) {
         return this._beatSteps.has(b.id) ? this._beatSteps.get(b.id).minStepsNote : null;
     }
-    static calculateNoteSteps(keySignature, clef, noteValue) {
-        const value = noteValue;
-        const ks = keySignature;
+    static calculateNoteSteps(clef, spelling) {
         const clefValue = clef;
-        const index = value % 12;
-        const octave = ((value / 12) | 0) - 1;
         // Initial Position
         let steps = AccidentalHelper._octaveSteps[clefValue];
         // Move to Octave
-        steps -= octave * AccidentalHelper._stepsPerOctave;
-        // get the step list for the current keySignature
-        const stepList = ModelUtils.keySignatureIsSharp(ks) || ModelUtils.keySignatureIsNatural(ks)
-            ? AccidentalHelper.sharpNoteSteps
-            : AccidentalHelper.flatNoteSteps;
-        steps -= stepList[index];
+        steps -= spelling.octave * AccidentalHelper._stepsPerOctave;
+        // Move within octave
+        steps -= AccidentalHelper._diatonicSteps[spelling.degree];
         return steps;
     }
     getNoteSteps(n) {
@@ -25202,7 +25307,8 @@ class TrackInfo {
             musicXmlStaffSteps = 4; // middle of bar
         }
         else {
-            musicXmlStaffSteps = AccidentalHelper.calculateNoteSteps(bar.keySignature, bar.clef, noteValue);
+            const spelling = ModelUtils.resolveSpelling(bar.keySignature, noteValue, NoteAccidentalMode.Default);
+            musicXmlStaffSteps = AccidentalHelper.calculateNoteSteps(bar.clef, spelling);
         }
         // to translate this into the "staffLine" semantics we need to subtract additionally the steps "missing" from the absent lines
         const actualSteps = note.beat.voice.bar.staff.standardNotationLineCount * 2 - 1;
@@ -47056,9 +47162,14 @@ var MidiTickLookupFindBeatResultCursorMode;
      */
     MidiTickLookupFindBeatResultCursorMode[MidiTickLookupFindBeatResultCursorMode["ToNextBext"] = 1] = "ToNextBext";
     /**
-     * The cursor should animate to the end of the bar (typically on repeats and jumps)
+     * @deprecated replaced by {@link ToEndOfBeat}
      */
     MidiTickLookupFindBeatResultCursorMode[MidiTickLookupFindBeatResultCursorMode["ToEndOfBar"] = 2] = "ToEndOfBar";
+    /**
+     * The cursor should animate to the end of the **beat** (typically on repeats and jumps)
+     * (this is named end of bar historically)
+     */
+    MidiTickLookupFindBeatResultCursorMode[MidiTickLookupFindBeatResultCursorMode["ToEndOfBeat"] = 3] = "ToEndOfBeat";
 })(MidiTickLookupFindBeatResultCursorMode || (MidiTickLookupFindBeatResultCursorMode = {}));
 /**
  * Represents the results of searching the currently played beat.
@@ -47206,6 +47317,11 @@ class MidiTickLookup {
      * This info allows building the correct "next" beat and duration.
      */
     multiBarRestInfo = null;
+    /**
+     * An optional playback range to consider when performing lookups.
+     * This will mainly influence the used {@link MidiTickLookupFindBeatResultCursorMode}
+     */
+    playbackRange = null;
     /**
      * Finds the currently played beat given a list of tracks and the current time.
      * @param trackLookup The tracks indices in which to search the played beat for.
@@ -47231,6 +47347,13 @@ class MidiTickLookup {
         if (!result) {
             result = this._findBeatSlow(checker, currentBeatHint, tick, false);
         }
+        if (result) {
+            const playbackRange = this.playbackRange;
+            const isBeyondRangeEnd = playbackRange !== null && result.start >= playbackRange.endTick;
+            if (isBeyondRangeEnd) {
+                return null;
+            }
+        }
         return result;
     }
     _findBeatFast(checker, currentBeatHint, tick) {
@@ -47270,20 +47393,24 @@ class MidiTickLookup {
                 if (current.nextBeat) {
                     current.tickDuration = current.nextBeat.start - current.start;
                     current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToNextBext;
+                    // jump back
                     if (current.nextBeat.masterBar.masterBar.index !== endMasterBar.masterBar.index + 1 &&
                         (current.nextBeat.masterBar.masterBar.index !== endMasterBar.masterBar.index ||
                             current.nextBeat.beat.playbackStart <= current.beat.playbackStart)) {
-                        current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBar;
+                        current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBeat;
+                    }
+                    else if (this.playbackRange !== null && this.playbackRange.endTick <= current.nextBeat.start) {
+                        current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBeat;
                     }
                 }
                 else {
                     current.tickDuration = endMasterBar.nextMasterBar.end - current.start;
-                    current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBar;
+                    current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBeat;
                 }
             }
             else {
                 current.tickDuration = endMasterBar.end - current.start;
-                current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBar;
+                current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBeat;
             }
         }
         else {
@@ -47291,7 +47418,7 @@ class MidiTickLookup {
             // this is wierd, we  have a masterbar without known tick?
             // make a best guess with the number of bars
             current.tickDuration = (current.masterBar.end - current.masterBar.start) * (group.length + 1);
-            current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBar;
+            current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBeat;
         }
         current.calculateDuration();
     }
@@ -47317,16 +47444,20 @@ class MidiTickLookup {
         }
         else {
             current.tickDuration = current.masterBar.end - current.start;
-            current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBar;
+            current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBeat;
             current.calculateDuration();
         }
-        // if the next beat is not directly the next master bar (e.g. jumping back or forth)
-        // we report no next beat and animate to the end
-        if (current.nextBeat &&
-            current.nextBeat.masterBar.masterBar.index !== current.masterBar.masterBar.index + 1 &&
-            (current.nextBeat.masterBar.masterBar.index !== current.masterBar.masterBar.index ||
-                current.nextBeat.beat.playbackStart <= current.beat.playbackStart)) {
-            current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBar;
+        if (current.nextBeat) {
+            // if the next beat is not directly the next master bar (e.g. jumping back or forth)
+            // we report no next beat and animate to the end
+            if (current.nextBeat.masterBar.masterBar.index !== current.masterBar.masterBar.index + 1 &&
+                (current.nextBeat.masterBar.masterBar.index !== current.masterBar.masterBar.index ||
+                    current.nextBeat.beat.playbackStart <= current.beat.playbackStart)) {
+                current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBeat;
+            }
+            else if (this.playbackRange !== null && this.playbackRange.endTick <= current.nextBeat.start) {
+                current.cursorMode = MidiTickLookupFindBeatResultCursorMode.ToEndOfBeat;
+            }
         }
     }
     _isMultiBarRestResult(current) {
@@ -49352,22 +49483,61 @@ class MidiFileGenerator {
 }
 
 /**
- * Represents the information related to a resize event.
- * @public
+ * A cursor handler which animates the beat cursor to the next beat or end of the beat bounds
+ * depending on the cursor mode.
+ * @internal
  */
-class ResizeEventArgs {
-    /**
-     * Gets the size before the resizing happened.
-     */
-    oldWidth = 0;
-    /**
-     * Gets the size after the resize was complete.
-     */
-    newWidth = 0;
-    /**
-     * Gets the settings currently used for rendering.
-     */
-    settings = null;
+class ToNextBeatAnimatingCursorHandler {
+    onAttach(_cursors) {
+    }
+    onDetach(_cursors) {
+    }
+    placeBeatCursor(beatCursor, beatBounds, startBeatX) {
+        const barBoundings = beatBounds.barBounds.masterBarBounds;
+        const barBounds = barBoundings.visualBounds;
+        beatCursor.transitionToX(0, startBeatX);
+        beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
+    }
+    placeBarCursor(barCursor, beatBounds) {
+        const barBoundings = beatBounds.barBounds.masterBarBounds;
+        const barBounds = barBoundings.visualBounds;
+        barCursor.setBounds(barBounds.x, barBounds.y, barBounds.w, barBounds.h);
+    }
+    transitionBeatCursor(beatCursor, _beatBounds, startBeatX, nextBeatX, duration, cursorMode) {
+        // it can happen that the cursor reaches the target position slightly too early (especially on backing tracks)
+        // to avoid the cursor stopping, causing a wierd look, we animate the cursor to the double position in double time.
+        // beatCursor!.transitionToX((duration / cursorSpeed), nextBeatX);
+        const factor = cursorMode === MidiTickLookupFindBeatResultCursorMode.ToNextBext ? 2 : 1;
+        nextBeatX = startBeatX + (nextBeatX - startBeatX) * factor;
+        duration = duration * factor;
+        // we need to put the transition to an own animation frame
+        // otherwise the stop animation above is not applied.
+        beatCursor.transitionToX(duration, nextBeatX);
+    }
+}
+/**
+ * A cursor handler which just places the bar and beat cursor without any animations applied.
+ * @internal
+ */
+class NonAnimatingCursorHandler {
+    onAttach(_cursors) {
+    }
+    onDetach(_cursors) {
+    }
+    placeBeatCursor(beatCursor, beatBounds, startBeatX) {
+        const barBoundings = beatBounds.barBounds.masterBarBounds;
+        const barBounds = barBoundings.visualBounds;
+        beatCursor.transitionToX(0, startBeatX);
+        beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
+    }
+    placeBarCursor(barCursor, beatBounds) {
+        const barBoundings = beatBounds.barBounds.masterBarBounds;
+        const barBounds = barBoundings.visualBounds;
+        barCursor.setBounds(barBounds.x, barBounds.y, barBounds.w, barBounds.h);
+    }
+    transitionBeatCursor(beatCursor, beatBounds, startBeatX, _nextBeatX, _duration, _cursorMode) {
+        this.placeBeatCursor(beatCursor, beatBounds, startBeatX);
+    }
 }
 
 /**
@@ -49809,6 +49979,25 @@ class ScoreRendererWrapper {
     error = new EventEmitterOfT();
 }
 
+/**
+ * Represents the information related to a resize event.
+ * @public
+ */
+class ResizeEventArgs {
+    /**
+     * Gets the size before the resizing happened.
+     */
+    oldWidth = 0;
+    /**
+     * Gets the size after the resize was complete.
+     */
+    newWidth = 0;
+    /**
+     * Gets the settings currently used for rendering.
+     */
+    settings = null;
+}
+
 /**
  * Some basic scroll handler checking for changed offsets and scroll if changed.
  * @internal
@@ -50678,6 +50867,42 @@ class ExternalMediaPlayer extends BackingTrackPlayer {
     }
 }
 
+/**
+ * This wrapper holds all cursor related elements.
+ * @public
+ */
+class Cursors {
+    /**
+     * Gets the element that spans across the whole music sheet and holds the other cursor elements.
+     */
+    cursorWrapper;
+    /**
+     * Gets the element that is positioned above the bar that is currently played.
+     */
+    barCursor;
+    /**
+     * Gets the element that is positioned above the beat that is currently played.
+     */
+    beatCursor;
+    /**
+     * Gets the element that spans across the whole music sheet and will hold any selection related elements.
+     */
+    selectionWrapper;
+    /**
+     * Initializes a new instance of the {@link Cursors} class.
+     * @param cursorWrapper
+     * @param barCursor
+     * @param beatCursor
+     * @param selectionWrapper
+     */
+    constructor(cursorWrapper, barCursor, beatCursor, selectionWrapper) {
+        this.cursorWrapper = cursorWrapper;
+        this.barCursor = barCursor;
+        this.beatCursor = beatCursor;
+        this.selectionWrapper = selectionWrapper;
+    }
+}
+
 /**
  * @internal
  */
@@ -50709,6 +50934,8 @@ class AlphaTabApiBase {
     _player;
     _renderer;
     _defaultScrollHandler;
+    _defaultCursorHandler;
+    _customCursorHandler;
     /**
      * An indicator by how many midi-ticks the song contents are shifted.
      * Grace beats at start might require a shift for the first beat to start at 0.
@@ -51480,6 +51707,80 @@ class AlphaTabApiBase {
             this.uiFacade.canRenderChanged.on(() => this.render(renderHints));
         }
     }
+    /**
+     * A custom cursor handler which will be used to update the cursor positions during playback.
+     *
+     * @category Properties - Player
+     * @since 1.8.1
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * api.customCursorHandler = {
+     *   _customAdorner: undefined,
+     *   onAttach(cursors) {
+     *     this._customAdorner = document.createElement('div');
+     *     this._customAdorner.classList.add('cursor-adorner');
+     *     cursors.cursorWrapper.element.appendChild(this._customAdorner);
+     *   },
+     *   onDetach(cursors) { this._customAdorner.remove(); },
+     *   placeBarCursor(barCursor, beatBounds) {
+     *     const barBoundings = beatBounds.barBounds.masterBarBounds;
+     *     const barBounds = barBoundings.visualBounds;
+     *     barCursor.setBounds(barBounds.x, barBounds.y, barBounds.w, barBounds.h);
+     *   },
+     *   placeBeatCursor(beatCursor, beatBounds, startBeatX) {
+     *     const barBoundings = beatBounds.barBounds.masterBarBounds;
+     *     const barBounds = barBoundings.visualBounds;
+     *     beatCursor.transitionToX(0, startBeatX);
+     *     beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
+     *     this._customAdorner.style.left = startBeatX + 'px';
+     *     this._customAdorner.style.top = (barBounds.y - 10) + 'px';
+     *     this._customAdorner.style.width = '1px';
+     *     this._customAdorner.style.height = '10px';
+     *     this._customAdorner.style.transition = 'left 0ms linear'; // stop animation
+     *   },
+     *   transitionBeatCursor(beatCursor, beatBounds, startBeatX, endBeatX, duration, cursorMode) {
+     *     this._customAdorner.style.transition = `left ${duration}ms linear`; // start animation
+     *     this._customAdorner.style.left = endBeatX + 'px';
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.CustomCursorHandler = new CustomCursorHandler();
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * api.customCursorHandler = CustomCursorHandler();
+     * ```
+     */
+    get customCursorHandler() {
+        return this._customCursorHandler;
+    }
+    set customCursorHandler(value) {
+        if (this._customCursorHandler === value) {
+            return;
+        }
+        const currentHandler = this._customCursorHandler ?? this._defaultCursorHandler;
+        this._customCursorHandler = value;
+        if (this._cursorWrapper) {
+            const cursors = new Cursors(this._cursorWrapper, this._barCursor, this._beatCursor, this._selectionWrapper);
+            currentHandler?.onDetach(cursors);
+            if (value) {
+                value?.onDetach(cursors);
+            }
+            else if (this._defaultCursorHandler) {
+                this._defaultCursorHandler.onAttach(cursors);
+            }
+        }
+    }
     _tickCache = null;
     /**
      * A custom scroll handler which will be used to handle scrolling operations during playback.
@@ -51957,6 +52258,9 @@ class AlphaTabApiBase {
     }
     set playbackRange(value) {
         this._player.playbackRange = value;
+        if (this._tickCache) {
+            this._tickCache.playbackRange = value;
+        }
         this._updateSelectionCursor(value);
     }
     /**
@@ -52104,6 +52408,7 @@ class AlphaTabApiBase {
         generator.applyTranspositionPitches = false;
         generator.generate();
         this._tickCache = generator.tickLookup;
+        this._tickCache.playbackRange = this.playbackRange;
         this._onMidiLoad(midiFile);
         const player = this._player;
         player.midiTickShift = handler.tickShift;
@@ -52499,6 +52804,8 @@ class AlphaTabApiBase {
         if (!this._cursorWrapper) {
             return;
         }
+        const cursorHandler = this.customCursorHandler ?? this._defaultCursorHandler;
+        cursorHandler?.onDetach(new Cursors(this._cursorWrapper, this._barCursor, this._beatCursor, this._selectionWrapper));
         this.uiFacade.destroyCursors();
         this._cursorWrapper = null;
         this._barCursor = null;
@@ -52516,6 +52823,8 @@ class AlphaTabApiBase {
             this._barCursor = cursors.barCursor;
             this._beatCursor = cursors.beatCursor;
             this._selectionWrapper = cursors.selectionWrapper;
+            const cursorHandler = this.customCursorHandler ?? this._defaultCursorHandler;
+            cursorHandler?.onAttach(cursors);
             this._isInitialBeatCursorUpdate = true;
         }
         if (this._currentBeat !== null) {
@@ -52523,6 +52832,7 @@ class AlphaTabApiBase {
         }
     }
     _updateCursors() {
+        this._updateCursorHandler();
         this._updateScrollHandler();
         const enable = this._hasCursor;
         if (enable) {
@@ -52532,6 +52842,21 @@ class AlphaTabApiBase {
             this._destroyCursors();
         }
     }
+    _cursorHandlerMode = false;
+    _updateCursorHandler() {
+        const currentHandler = this._defaultCursorHandler;
+        const cursorHandlerMode = this.settings.player.enableAnimatedBeatCursor;
+        // no change
+        if (currentHandler !== undefined && this._cursorHandlerMode === cursorHandlerMode) {
+            return;
+        }
+        if (cursorHandlerMode) {
+            this._defaultCursorHandler = new ToNextBeatAnimatingCursorHandler();
+        }
+        else {
+            this._defaultCursorHandler = new NonAnimatingCursorHandler();
+        }
+    }
     _scrollHandlerMode = ScrollMode.Off;
     _scrollHandlerVertical = true;
     _updateScrollHandler() {
@@ -52599,9 +52924,6 @@ class AlphaTabApiBase {
      */
     _cursorUpdateBeat(lookupResult, stop, shouldScroll, cursorSpeed, forceUpdate = false) {
         const beat = lookupResult.beat;
-        const nextBeat = lookupResult.nextBeat?.beat ?? null;
-        const duration = lookupResult.duration;
-        const beatsToHighlight = lookupResult.beatLookup.highlightedBeats;
         if (!beat) {
             return;
         }
@@ -52629,7 +52951,7 @@ class AlphaTabApiBase {
         this._previousCursorCache = cache;
         this._previousStateForCursor = this._player.state;
         this.uiFacade.beginInvoke(() => {
-            this._internalCursorUpdateBeat(beat, nextBeat, duration, stop, beatsToHighlight, cache, beatBoundings, shouldScroll, lookupResult.cursorMode, cursorSpeed);
+            this._internalCursorUpdateBeat(lookupResult, stop, cache, beatBoundings, shouldScroll, cursorSpeed);
         });
     }
     /**
@@ -52646,24 +52968,30 @@ class AlphaTabApiBase {
             }
         }
     }
-    _internalCursorUpdateBeat(beat, nextBeat, duration, stop, beatsToHighlight, cache, beatBoundings, shouldScroll, cursorMode, cursorSpeed) {
-        const barCursor = this._barCursor;
+    _internalCursorUpdateBeat(lookupResult, stop, boundsLookup, beatBoundings, shouldScroll, cursorSpeed) {
+        const beat = lookupResult.beat;
+        const nextBeat = lookupResult.nextBeat?.beat;
+        let duration = lookupResult.duration;
+        const beatsToHighlight = lookupResult.beatLookup.highlightedBeats;
+        const cursorMode = lookupResult.cursorMode;
+        const cursorHandler = this.customCursorHandler ?? this._defaultCursorHandler;
         const beatCursor = this._beatCursor;
+        const barCursor = this._barCursor;
         const barBoundings = beatBoundings.barBounds.masterBarBounds;
         const barBounds = barBoundings.visualBounds;
         const previousBeatBounds = this._currentBeatBounds;
         this._currentBeatBounds = beatBoundings;
         if (barCursor) {
-            barCursor.setBounds(barBounds.x, barBounds.y, barBounds.w, barBounds.h);
+            cursorHandler.placeBarCursor(barCursor, beatBoundings);
         }
         const isPlayingUpdate = this._player.state === PlayerState.Playing && !stop;
-        let nextBeatX = barBoundings.visualBounds.x + barBoundings.visualBounds.w;
+        let nextBeatX = beatBoundings.realBounds.x + beatBoundings.realBounds.w;
         let nextBeatBoundings = null;
         // get position of next beat on same system
         if (nextBeat && cursorMode === MidiTickLookupFindBeatResultCursorMode.ToNextBext) {
             // if we are moving within the same bar or to the next bar
             // transition to the next beat, otherwise transition to the end of the bar.
-            nextBeatBoundings = cache.findBeat(nextBeat);
+            nextBeatBoundings = boundsLookup.findBeat(nextBeat);
             if (nextBeatBoundings &&
                 nextBeatBoundings.barBounds.masterBarBounds.staffSystemBounds === barBoundings.staffSystemBounds) {
                 nextBeatX = nextBeatBoundings.onNotesX;
@@ -52671,48 +52999,30 @@ class AlphaTabApiBase {
         }
         let startBeatX = beatBoundings.onNotesX;
         if (beatCursor) {
-            // relative positioning of the cursor
-            if (this.settings.player.enableAnimatedBeatCursor) {
-                const animationWidth = nextBeatX - beatBoundings.onNotesX;
-                const relativePosition = this._previousTick - this._currentBeat.start;
-                const ratioPosition = this._currentBeat.tickDuration > 0 ? relativePosition / this._currentBeat.tickDuration : 0;
-                startBeatX = beatBoundings.onNotesX + animationWidth * ratioPosition;
-                duration -= duration * ratioPosition;
-                if (isPlayingUpdate) {
-                    // we do not "reset" the cursor if we are smoothly moving from left to right.
-                    const jumpCursor = !previousBeatBounds ||
-                        this._isInitialBeatCursorUpdate ||
-                        barBounds.y !== previousBeatBounds.barBounds.masterBarBounds.visualBounds.y ||
-                        startBeatX < previousBeatBounds.onNotesX ||
-                        barBoundings.index > previousBeatBounds.barBounds.masterBarBounds.index + 1;
-                    if (jumpCursor) {
-                        beatCursor.transitionToX(0, startBeatX);
-                        beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
-                    }
-                    // it can happen that the cursor reaches the target position slightly too early (especially on backing tracks)
-                    // to avoid the cursor stopping, causing a wierd look, we animate the cursor to the double position in double time.
-                    // beatCursor!.transitionToX((duration / cursorSpeed), nextBeatX);
-                    const factor = cursorMode === MidiTickLookupFindBeatResultCursorMode.ToNextBext ? 2 : 1;
-                    nextBeatX = startBeatX + (nextBeatX - startBeatX) * factor;
-                    duration = (duration / cursorSpeed) * factor;
-                    // we need to put the transition to an own animation frame
-                    // otherwise the stop animation above is not applied.
-                    this.uiFacade.beginInvoke(() => {
-                        beatCursor.transitionToX(duration, nextBeatX);
-                    });
-                }
-                else {
-                    duration = 0;
-                    beatCursor.transitionToX(duration, nextBeatX);
-                    beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
-                }
+            const animationWidth = nextBeatX - beatBoundings.onNotesX;
+            const relativePosition = this._previousTick - this._currentBeat.start;
+            const ratioPosition = this._currentBeat.tickDuration > 0 ? relativePosition / this._currentBeat.tickDuration : 0;
+            startBeatX = beatBoundings.onNotesX + animationWidth * ratioPosition;
+            duration -= duration * ratioPosition;
+            // respect speed
+            duration = duration / cursorSpeed;
+            if (isPlayingUpdate) {
+                // we do not "reset" the cursor if we are smoothly moving from left to right.
+                const jumpCursor = !previousBeatBounds ||
+                    this._isInitialBeatCursorUpdate ||
+                    barBounds.y !== previousBeatBounds.barBounds.masterBarBounds.visualBounds.y ||
+                    startBeatX < previousBeatBounds.onNotesX ||
+                    barBoundings.index > previousBeatBounds.barBounds.masterBarBounds.index + 1;
+                if (jumpCursor) {
+                    cursorHandler.placeBeatCursor(beatCursor, beatBoundings, startBeatX);
+                }
+                this.uiFacade.beginInvoke(() => {
+                    cursorHandler.transitionBeatCursor(beatCursor, beatBoundings, startBeatX, nextBeatX, duration, cursorMode);
+                });
             }
             else {
-                // ticking cursor
                 duration = 0;
-                nextBeatX = startBeatX;
-                beatCursor.transitionToX(duration, nextBeatX);
-                beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
+                cursorHandler.placeBeatCursor(beatCursor, beatBoundings, startBeatX);
             }
             this._isInitialBeatCursorUpdate = false;
         }
@@ -55589,42 +55899,6 @@ class AlphaTabWorkerScoreRenderer {
     error = new EventEmitterOfT();
 }
 
-/**
- * This wrapper holds all cursor related elements.
- * @public
- */
-class Cursors {
-    /**
-     * Gets the element that spans across the whole music sheet and holds the other cursor elements.
-     */
-    cursorWrapper;
-    /**
-     * Gets the element that is positioned above the bar that is currently played.
-     */
-    barCursor;
-    /**
-     * Gets the element that is positioned above the beat that is currently played.
-     */
-    beatCursor;
-    /**
-     * Gets the element that spans across the whole music sheet and will hold any selection related elements.
-     */
-    selectionWrapper;
-    /**
-     * Initializes a new instance of the {@link Cursors} class.
-     * @param cursorWrapper
-     * @param barCursor
-     * @param beatCursor
-     * @param selectionWrapper
-     */
-    constructor(cursorWrapper, barCursor, beatCursor, selectionWrapper) {
-        this.cursorWrapper = cursorWrapper;
-        this.barCursor = barCursor;
-        this.beatCursor = beatCursor;
-        this.selectionWrapper = selectionWrapper;
-    }
-}
-
 /**
  * An IContainer implementation which can be used for cursors and select ranges
  * where browser scaling is relevant.
@@ -59928,11 +60202,12 @@ class NumberedKeySignatureGlyph extends EffectGlyph {
     }
     doLayout() {
         super.doLayout();
-        const text = '1 = ';
+        let text = '';
         let text2 = '';
         let accidental = AccidentalType.None;
         switch (this._keySignatureType) {
             case KeySignatureType.Major:
+                text = '1 = ';
                 switch (this._keySignature) {
                     case KeySignature.Cb:
                         text2 = '  C';
@@ -59996,6 +60271,7 @@ class NumberedKeySignatureGlyph extends EffectGlyph {
                 }
                 break;
             case KeySignatureType.Minor:
+                text = '6 = ';
                 switch (this._keySignature) {
                     case KeySignature.Cb:
                         text2 = '  a';
@@ -67975,7 +68251,6 @@ class SpacingGlyph extends Glyph {
  * @internal
  */
 class NumberedBeatPreNotesGlyph extends BeatGlyphBase {
-    isNaturalizeAccidental = false;
     accidental = AccidentalType.None;
     skipLayout = false;
     get effectElement() {
@@ -67990,25 +68265,25 @@ class NumberedBeatPreNotesGlyph extends BeatGlyphBase {
             accidentals.renderer = this.renderer;
             if (this.container.beat.notes.length > 0) {
                 const note = this.container.beat.notes[0];
-                // Notes
-                // - Compared to standard notation accidentals:
-                //   - Flat keysigs: When there is a naturalize symbol (against key signature, not naturalizing same line) we have a # in Numbered notation
-                //   - Flat keysigs: When there is a flat symbol standard notation we also have a flat in Numbered notation
-                //   - C keysig: A sharp on standard notation is a sharp on numbered notation
-                //   - # keysigs:  When there is a # symbol on standard notation we also a sharp in numbered notation
-                //   - # keysigs:  When there is a naturalize symbol (against key signature, not naturalizing same line) we have a flat in Numbered notation
-                // Or generally:
-                //  - numbered notation has the same accidentals as standard notation if applied
-                //  - when the standard notation naturalizes the accidental from the key signature, the numbered notation has the reversed accidental
-                const accidentalMode = note ? note.accidentalMode : NoteAccidentalMode.Default;
-                const noteValue = AccidentalHelper.getNoteValue(note);
-                let accidentalToSet = ModelUtils.computeAccidental(this.renderer.bar.keySignature, accidentalMode, noteValue, note.hasQuarterToneOffset);
-                if (accidentalToSet === AccidentalType.Natural) {
-                    const ks = this.renderer.bar.keySignature;
-                    const ksi = ks + 7;
-                    const naturalizeAccidentalForKeySignature = ksi < 7 ? AccidentalType.Sharp : AccidentalType.Flat;
-                    accidentalToSet = naturalizeAccidentalForKeySignature;
-                    this.isNaturalizeAccidental = true;
+                const spelling = ModelUtils.resolveSpelling(this.renderer.bar.keySignature, note.displayValue, note.accidentalMode);
+                const ksOffset = ModelUtils.getKeySignatureAccidentalOffset(this.renderer.bar.keySignature, spelling.degree);
+                const requiredOffset = spelling.accidentalOffset - ksOffset;
+                let accidentalToSet = AccidentalType.None;
+                if (note.accidentalMode !== NoteAccidentalMode.ForceNone) {
+                    if (note.hasQuarterToneOffset) {
+                        if (requiredOffset > 0) {
+                            accidentalToSet = AccidentalType.SharpQuarterNoteUp;
+                        }
+                        else if (requiredOffset < 0) {
+                            accidentalToSet = AccidentalType.FlatQuarterNoteUp;
+                        }
+                        else {
+                            accidentalToSet = AccidentalType.NaturalQuarterNoteUp;
+                        }
+                    }
+                    else if (requiredOffset !== 0) {
+                        accidentalToSet = ModelUtils.accidentalOffsetToType(requiredOffset);
+                    }
                 }
                 // do we need an accidental on the note?
                 if (accidentalToSet !== AccidentalType.None) {
@@ -68115,21 +68390,21 @@ class NumberedBeatGlyph extends BeatOnNoteGlyphBase {
         }
         return 0;
     }
-    static majorKeySignatureOneValues = [
-        // Flats
-        59, 66, 61, 68, 63, 58, 65,
-        // natural
+    static _majorKeySignatureOneValues = [
+        // Flats: Cb, Gb, Db, Ab, Eb, Bb, F
+        59, 66, 61, 68, 63, 70, 65,
+        // natural: C
         60,
-        // sharps  (where the value is true, a flat accidental is required for the notes)
+        // sharps: G, D, A, E, B, F#, C#
         67, 62, 69, 64, 71, 66, 61
     ];
-    static minorKeySignatureOneValues = [
-        // Flats
-        71, 66, 73, 68, 63, 70, 65,
-        // natural
-        72,
-        // sharps  (where the value is true, a flat accidental is required for the notes)
-        67, 74, 69, 64, 71, 66, 73
+    static _minorKeySignatureOneValues = [
+        // Flats: Ab, Eb, Bb, F, C, G, D
+        68, 63, 70, 65, 60, 67, 62,
+        // natural: A
+        69,
+        // sharps: E, B, F#, C#, G#, D#, A#
+        64, 71, 66, 61, 68, 63, 70
     ];
     doLayout() {
         // create glyphs
@@ -68143,38 +68418,26 @@ class NumberedBeatGlyph extends BeatOnNoteGlyphBase {
             let numberWithinOctave = '0';
             if (this.container.beat.notes.length > 0) {
                 const note = this.container.beat.notes[0];
-                const kst = this.renderer.bar.keySignatureType;
-                const ks = this.renderer.bar.keySignature;
-                const ksi = ks + 7;
-                const oneNoteValues = kst === KeySignatureType.Minor
-                    ? NumberedBeatGlyph.minorKeySignatureOneValues
-                    : NumberedBeatGlyph.majorKeySignatureOneValues;
-                const oneNoteValue = oneNoteValues[ksi];
                 if (note.isDead) {
                     numberWithinOctave = 'X';
                 }
                 else {
+                    const ks = this.renderer.bar.keySignature;
+                    const kst = this.renderer.bar.keySignatureType;
+                    const ksi = ks + 7;
+                    const oneNoteValues = kst === KeySignatureType.Minor
+                        ? NumberedBeatGlyph._minorKeySignatureOneValues
+                        : NumberedBeatGlyph._majorKeySignatureOneValues;
+                    const oneNoteValue = oneNoteValues[ksi];
+                    const spelling = ModelUtils.resolveSpelling(ks, note.displayValue, note.accidentalMode);
+                    const tonicDegree = ModelUtils.getKeySignatureTonicDegree(ks, kst);
+                    const effectiveTonic = kst === KeySignatureType.Minor
+                        ? (tonicDegree + 2) % 7 // relative major
+                        : tonicDegree;
+                    const degreeDistance = (spelling.degree - effectiveTonic + 7) % 7;
+                    numberWithinOctave = (degreeDistance + 1).toString();
                     const noteValue = note.displayValue - oneNoteValue;
-                    const index = noteValue < 0 ? ((noteValue % 12) + 12) % 12 : noteValue % 12;
-                    octaveDots = noteValue < 0 ? ((Math.abs(noteValue) + 12) / 12) | 0 : (noteValue / 12) | 0;
-                    if (noteValue < 0) {
-                        octaveDots *= -1;
-                    }
-                    const stepList = ModelUtils.keySignatureIsSharp(ks) || ModelUtils.keySignatureIsNatural(ks)
-                        ? AccidentalHelper.flatNoteSteps
-                        : AccidentalHelper.sharpNoteSteps;
-                    let steps = stepList[index] + 1;
-                    const hasAccidental = ModelUtils.accidentalNotes[index];
-                    if (hasAccidental &&
-                        !this.container.preNotes.isNaturalizeAccidental) {
-                        if (ksi < 7) {
-                            steps++;
-                        }
-                        else {
-                            steps--;
-                        }
-                    }
-                    numberWithinOctave = steps.toString();
+                    octaveDots = Math.floor(noteValue / 12);
                 }
             }
             if (this.container.beat.deadSlapped) {