@coderline/alphatab 1.8.0 → 1.8.1

package/dist/alphaTab.js

@@ -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.
  *
@@ -209,9 +209,9 @@
      * @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}`);
@@ -4525,135 +4525,6 @@
                 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
          */
@@ -4692,6 +4563,239 @@
             }
             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];
+        }
     }
 
     /**
@@ -5402,7 +5506,8 @@
                     }
                 }
             }
-            return 'unknown';
+            // unknown combination, should not happen, fallback to some default value (Snare hit)
+            return 'Snare (hit)';
         }
         static getArticulation(n) {
             const articulationIndex = n.percussionArticulation;
@@ -15578,7 +15683,11 @@
                 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) {
@@ -19543,6 +19652,24 @@
      */
     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;
@@ -19889,9 +20016,9 @@
             }
         }
         /**
-         * 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);
@@ -20612,7 +20739,9 @@
                 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;
             }
@@ -23864,6 +23993,9 @@
                     switch (c.localName) {
                         case 'Accidental':
                             switch (c.innerText) {
+                                case '':
+                                    note.accidentalMode = NoteAccidentalMode.ForceNatural;
+                                    break;
                                 case 'x':
                                     note.accidentalMode = NoteAccidentalMode.ForceDoubleSharp;
                                     break;
@@ -24902,13 +25034,9 @@
          */
         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();
@@ -24940,23 +25068,7 @@
             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.
@@ -24988,7 +25100,8 @@
                 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;
         }
@@ -25001,11 +25114,12 @@
             }
             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:
@@ -25030,14 +25144,12 @@
                         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);
@@ -25089,21 +25201,14 @@
         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) {
@@ -25208,7 +25313,8 @@
                 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;
@@ -47062,9 +47168,14 @@
          */
         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.
@@ -47212,6 +47323,11 @@
          * 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.
@@ -47237,6 +47353,13 @@
             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) {
@@ -47276,20 +47399,24 @@
                     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 {
@@ -47297,7 +47424,7 @@
                 // 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();
         }
@@ -47323,16 +47450,20 @@
             }
             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) {
@@ -49358,22 +49489,61 @@
     }
 
     /**
-     * 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);
+        }
     }
 
     /**
@@ -49815,6 +49985,25 @@
         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
@@ -50684,6 +50873,42 @@
         }
     }
 
+    /**
+     * 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
      */
@@ -50715,6 +50940,8 @@
         _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.
@@ -51486,6 +51713,80 @@
                 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.
@@ -51963,6 +52264,9 @@
         }
         set playbackRange(value) {
             this._player.playbackRange = value;
+            if (this._tickCache) {
+                this._tickCache.playbackRange = value;
+            }
             this._updateSelectionCursor(value);
         }
         /**
@@ -52110,6 +52414,7 @@
             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;
@@ -52505,6 +52810,8 @@
             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;
@@ -52522,6 +52829,8 @@
                 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) {
@@ -52529,6 +52838,7 @@
             }
         }
         _updateCursors() {
+            this._updateCursorHandler();
             this._updateScrollHandler();
             const enable = this._hasCursor;
             if (enable) {
@@ -52538,6 +52848,21 @@
                 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 = exports.ScrollMode.Off;
         _scrollHandlerVertical = true;
         _updateScrollHandler() {
@@ -52605,9 +52930,6 @@
          */
         _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;
             }
@@ -52635,7 +52957,7 @@
             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);
             });
         }
         /**
@@ -52652,24 +52974,30 @@
                 }
             }
         }
-        _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;
@@ -52677,48 +53005,30 @@
             }
             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;
             }
@@ -55595,42 +55905,6 @@
         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.
@@ -59934,11 +60208,12 @@
         }
         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';
@@ -60002,6 +60277,7 @@
                     }
                     break;
                 case KeySignatureType.Minor:
+                    text = '6 = ';
                     switch (this._keySignature) {
                         case KeySignature.Cb:
                             text2 = '  a';
@@ -67981,7 +68257,6 @@
      * @internal
      */
     class NumberedBeatPreNotesGlyph extends BeatGlyphBase {
-        isNaturalizeAccidental = false;
         accidental = AccidentalType.None;
         skipLayout = false;
         get effectElement() {
@@ -67996,25 +68271,25 @@
                 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) {
@@ -68121,21 +68396,21 @@
             }
             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
@@ -68149,38 +68424,26 @@
                 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) {