@coderline/alphatab 1.8.0-alpha.1670 → 1.8.0-alpha.1671

package/dist/alphaTab.core.mjs

@@ -1,5 +1,5 @@
 /*!
- * alphaTab v1.8.0-alpha.1670 (develop, build 1670)
+ * alphaTab v1.8.0-alpha.1671 (develop, build 1671)
  *
  * 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-alpha.1670';
-    static date = '2026-01-09T02:24:51.076Z';
-    static commit = 'c4cd0c6435ec1bed778365efd389cb1b52df7ff3';
+    static version = '1.8.0-alpha.1671';
+    static date = '2026-01-10T02:20:48.787Z';
+    static commit = '1edf83d58fe31a924adb1980bc4a529aed07dad4';
     static print(print) {
         print(`alphaTab ${VersionInfo.version}`);
         print(`commit: ${VersionInfo.commit}`);
@@ -2196,6 +2196,12 @@ class Bar {
      * If specified, overrides the value from the stylesheet on score level.
      */
     barNumberDisplay;
+    /**
+     * The shortest duration contained across beats in this bar.
+     * @internal
+     * @json_ignore
+     */
+    shortestDuration = Duration.DoubleWhole;
     /**
      * The bar line to draw on the left side of the bar with an "automatic" type resolved to the actual one.
      * @param isFirstOfSystem  Whether the bar is the first one in the system.
@@ -2267,12 +2273,16 @@ class Bar {
         this._filledVoices.add(0);
         this._isEmpty = true;
         this._isRestOnly = true;
+        this.shortestDuration = Duration.DoubleWhole;
         for (let i = 0, j = this.voices.length; i < j; i++) {
             const voice = this.voices[i];
             voice.finish(settings, sharedDataBag);
             if (!voice.isEmpty) {
                 this._isEmpty = false;
                 this._filledVoices.add(i);
+                if (voice.shortestDuration > this.shortestDuration) {
+                    this.shortestDuration = voice.shortestDuration;
+                }
             }
             if (!voice.isRestOnly) {
                 this._isRestOnly = false;
@@ -2369,6 +2379,116 @@ var TripletFeel;
     TripletFeel[TripletFeel["Scottish8th"] = 6] = "Scottish8th";
 })(TripletFeel || (TripletFeel = {}));
 
+/**
+ * Defines the custom beaming rules which define how beats are beamed together or split apart
+ * during the automatic beaming when displayed.
+ * @json
+ * @json_strict
+ * @public
+ *
+ * @remarks
+ * The beaming logic works like this:
+ *
+ * The time axis of the bar is sliced into even chunks. The chunk-size is defined by the respective group definition.
+ * Within these chunks groups can then be placed spanning 1 or more chunks.
+ *
+ * If beats start within the same "group" they are beamed together.
+ */
+class BeamingRules {
+    _singleGroupKey;
+    /**
+     * The the group for a given "longest duration" within the bar.
+     * @remarks
+     * The map key is the duration to which the bar will be sliced into.
+     * The map value defines the "groups" placed within the sliced.
+     */
+    groups = new Map();
+    /**
+     * @internal
+     * @json_ignore
+     */
+    uniqueId = '';
+    /**
+     * @internal
+     * @json_ignore
+     */
+    timeSignatureNumerator = 0;
+    /**
+     * @internal
+     * @json_ignore
+     */
+    timeSignatureDenominator = 0;
+    /**
+     * @internal
+     */
+    static createSimple(timeSignatureNumerator, timeSignatureDenominator, duration, groups) {
+        const r = new BeamingRules();
+        r.timeSignatureNumerator = timeSignatureNumerator;
+        r.timeSignatureDenominator = timeSignatureDenominator;
+        r.groups.set(duration, groups);
+        r.finish();
+        return r;
+    }
+    /**
+     * @internal
+     */
+    findRule(shortestDuration) {
+        // fast path: one rule -> take it
+        const singleGroupKey = this._singleGroupKey;
+        if (singleGroupKey) {
+            return [singleGroupKey, this.groups.get(singleGroupKey)];
+        }
+        if (shortestDuration < Duration.Quarter) {
+            return [shortestDuration, []];
+        }
+        // first search shorter
+        let durationValue = shortestDuration;
+        do {
+            const duration = durationValue;
+            if (this.groups.has(duration)) {
+                return [duration, this.groups.get(duration)];
+            }
+            durationValue = durationValue * 2;
+        } while (durationValue <= Duration.TwoHundredFiftySixth);
+        // then longer
+        durationValue = shortestDuration / 2;
+        do {
+            const duration = durationValue;
+            if (this.groups.has(duration)) {
+                return [duration, this.groups.get(duration)];
+            }
+            durationValue = durationValue / 2;
+        } while (durationValue > Duration.Half);
+        return [shortestDuration, []];
+    }
+    /**
+     * @internal
+     */
+    finish() {
+        let uniqueId = `${this.timeSignatureNumerator}_${this.timeSignatureDenominator}`;
+        for (const [k, v] of this.groups) {
+            uniqueId += `__${k}`;
+            // trim of 0s at the end of the group
+            let lastZero = v.length;
+            for (let i = v.length - 1; i >= 0; i--) {
+                if (v[i] === 0) {
+                    lastZero = i;
+                }
+                else {
+                    break;
+                }
+            }
+            if (lastZero < v.length) {
+                v.splice(lastZero, v.length - lastZero);
+            }
+            uniqueId += `_${v.join('_')}`;
+            if (this.groups.size === 1) {
+                this._singleGroupKey = k;
+            }
+        }
+        this.uniqueId = uniqueId;
+    }
+}
 /**
  * The MasterBar stores information about a bar which affects
  * all tracks.
@@ -2486,6 +2606,16 @@ class MasterBar {
      * Gets or sets whether this is bar has a common time signature.
      */
     timeSignatureCommon = false;
+    /**
+     * Defines the custom beaming rules which should be applied to this bar and all bars following.
+     */
+    beamingRules;
+    /**
+     * The actual (custom) beaming rules to use for this bar if any were specified.
+     * @json_ignore
+     * @internal
+     */
+    actualBeamingRules;
     /**
      * Gets or sets whether the bar indicates a free time playing.
      */
@@ -2618,6 +2748,32 @@ class MasterBar {
         }
         this.syncPoints.push(syncPoint);
     }
+    finish(sharedDataBag) {
+        let beamingRules = this.beamingRules;
+        if (beamingRules) {
+            beamingRules.timeSignatureNumerator = this.timeSignatureNumerator;
+            beamingRules.timeSignatureDenominator = this.timeSignatureDenominator;
+            beamingRules.finish();
+        }
+        if (this.index > 0) {
+            this.start = this.previousMasterBar.start + this.previousMasterBar.calculateDuration();
+            // clear out equal rules to reduce memory consumption.
+            const previousRules = sharedDataBag.has('beamingRules')
+                ? sharedDataBag.get('beamingRules')
+                : undefined;
+            if (previousRules && previousRules.uniqueId === beamingRules?.uniqueId) {
+                this.beamingRules = undefined;
+                beamingRules = previousRules;
+            }
+            else if (!beamingRules) {
+                beamingRules = previousRules;
+            }
+        }
+        this.actualBeamingRules = beamingRules;
+        if (this.beamingRules) {
+            sharedDataBag.set('beamingRules', beamingRules);
+        }
+    }
 }
 
 /**
@@ -2968,6 +3124,12 @@ let Voice$1 = class Voice {
     get isRestOnly() {
         return this._isRestOnly;
     }
+    /**
+     * The shortest duration contained across beats in this bar.
+     * @internal
+     * @json_ignore
+     */
+    shortestDuration = Duration.DoubleWhole;
     insertBeat(after, newBeat) {
         newBeat.nextBeat = after.nextBeat;
         if (newBeat.nextBeat) {
@@ -3061,6 +3223,7 @@ let Voice$1 = class Voice {
         }
         let currentDisplayTick = 0;
         let currentPlaybackTick = 0;
+        this.shortestDuration = Duration.DoubleWhole;
         for (let i = 0; i < this.beats.length; i++) {
             const beat = this.beats[i];
             beat.index = i;
@@ -3069,6 +3232,9 @@ let Voice$1 = class Voice {
             // we need to first steal the duration from the right beat
             // and place the grace beats correctly
             if (beat.graceType === GraceType.None) {
+                if (beat.duration > this.shortestDuration) {
+                    this.shortestDuration = beat.duration;
+                }
                 if (beat.graceGroup) {
                     const firstGraceBeat = beat.graceGroup.beats[0];
                     const lastGraceBeat = beat.graceGroup.beats[beat.graceGroup.beats.length - 1];
@@ -3529,7 +3695,7 @@ class Score {
             bar.previousMasterBar.nextMasterBar = bar;
             // NOTE: this will not work on anacrusis. Correct anacrusis durations are only working
             // when there are beats with playback positions already computed which requires full finish
-            // chicken-egg problem here. temporarily forcing anacrusis length here to 0, 
+            // chicken-egg problem here. temporarily forcing anacrusis length here to 0,
             // .finish() will correct these times
             bar.start =
                 bar.previousMasterBar.start +
@@ -3593,9 +3759,7 @@ class Score {
         }
         // fixup masterbar starts to handle anacrusis lengths
         for (const mb of this.masterBars) {
-            if (mb.index > 0) {
-                mb.start = mb.previousMasterBar.start + mb.previousMasterBar.calculateDuration();
-            }
+            mb.finish(sharedDataBag);
         }
     }
     /**
@@ -8964,7 +9128,16 @@ class AlphaTex1LanguageDefinitions {
         ['spu', [[[[16], 2]]]],
         ['db', null],
         ['voicemode', [[[[10, 17], 0, ['staffwise', 'barwise']]]]],
-        ['barnumberdisplay', [[[[10, 17], 0, ['allbars', 'firstofsystem', 'hide']]]]]
+        ['barnumberdisplay', [[[[10, 17], 0, ['allbars', 'firstofsystem', 'hide']]]]],
+        [
+            'beaming',
+            [
+                [
+                    [[16], 0],
+                    [[16], 5]
+                ]
+            ]
+        ]
     ]);
     static metaDataProperties = AlphaTex1LanguageDefinitions._metaProps([
         [
@@ -9080,7 +9253,8 @@ class AlphaTex1LanguageDefinitions {
         ['spu', null],
         ['db', null],
         ['voicemode', null],
-        ['barnumberdisplay', null]
+        ['barnumberdisplay', null],
+        ['beaming', null]
     ]);
     static metaDataSignatures = [
         AlphaTex1LanguageDefinitions.scoreMetaDataSignatures,
@@ -12795,6 +12969,7 @@ var BeamDirection;
  */
 class AlphaTex1LanguageHandler {
     static instance = new AlphaTex1LanguageHandler();
+    static _timeSignatureDenominators = new Set([1, 2, 4, 8, 16, 32, 64, 128]);
     applyScoreMetaData(importer, score, metaData) {
         const result = this._checkArgumentTypes(importer, [AlphaTex1LanguageDefinitions.scoreMetaDataSignatures], metaData, metaData.tag.tag.text.toLowerCase(), metaData.arguments);
         if (result !== undefined) {
@@ -13216,8 +13391,29 @@ class AlphaTex1LanguageHandler {
             case 'ts':
                 switch (metaData.arguments.arguments[0].nodeType) {
                     case AlphaTexNodeType.Number:
-                        bar.masterBar.timeSignatureNumerator = metaData.arguments.arguments[0].value;
-                        bar.masterBar.timeSignatureDenominator = metaData.arguments.arguments[1].value;
+                        bar.masterBar.timeSignatureNumerator =
+                            metaData.arguments.arguments[0].value | 0;
+                        if (bar.masterBar.timeSignatureNumerator < 1 || bar.masterBar.timeSignatureNumerator > 32) {
+                            importer.addSemanticDiagnostic({
+                                code: AlphaTexDiagnosticCode.AT211,
+                                message: `Value is out of valid range. Allowed range: 1-32, Actual Value: ${bar.masterBar.timeSignatureNumerator}`,
+                                start: metaData.arguments.arguments[0].start,
+                                end: metaData.arguments.arguments[0].end,
+                                severity: AlphaTexDiagnosticsSeverity.Error
+                            });
+                        }
+                        bar.masterBar.timeSignatureDenominator =
+                            metaData.arguments.arguments[1].value | 0;
+                        if (!AlphaTex1LanguageHandler._timeSignatureDenominators.has(bar.masterBar.timeSignatureDenominator)) {
+                            const valueList = Array.from(AlphaTex1LanguageHandler._timeSignatureDenominators).join(', ');
+                            importer.addSemanticDiagnostic({
+                                code: AlphaTexDiagnosticCode.AT211,
+                                message: `Value is out of valid range. Allowed range: ${valueList}, Actual Value: ${bar.masterBar.timeSignatureDenominator}`,
+                                start: metaData.arguments.arguments[0].start,
+                                end: metaData.arguments.arguments[0].end,
+                                severity: AlphaTexDiagnosticsSeverity.Error
+                            });
+                        }
                         break;
                     case AlphaTexNodeType.Ident:
                     case AlphaTexNodeType.String:
@@ -13240,6 +13436,8 @@ class AlphaTex1LanguageHandler {
                         break;
                 }
                 return ApplyNodeResult.Applied;
+            case 'beaming':
+                return this._parseBeamingRule(importer, metaData, bar.masterBar);
             case 'ks':
                 const keySignature = AlphaTex1LanguageHandler._parseEnumValue(importer, metaData.arguments, 'key signature', AlphaTex1EnumMappings.keySignature);
                 if (keySignature === undefined) {
@@ -13440,6 +13638,53 @@ class AlphaTex1LanguageHandler {
                 return ApplyNodeResult.NotAppliedUnrecognizedMarker;
         }
     }
+    _parseBeamingRule(importer, metaData, masterBar) {
+        let duration = Duration.Eighth;
+        const groupSizes = [];
+        const durationValue = metaData.arguments.arguments[0].value;
+        switch (durationValue) {
+            case 4:
+                duration = Duration.QuadrupleWhole;
+                break;
+            case 8:
+                duration = Duration.Eighth;
+                break;
+            case 16:
+                duration = Duration.Sixteenth;
+                break;
+            case 32:
+                duration = Duration.ThirtySecond;
+                break;
+            default:
+                importer.addSemanticDiagnostic({
+                    code: AlphaTexDiagnosticCode.AT209,
+                    message: `Value is out of valid range. Allowed range: 4,8,16 or 32, Actual Value: ${durationValue}`,
+                    severity: AlphaTexDiagnosticsSeverity.Error,
+                    start: metaData.arguments.arguments[0].start,
+                    end: metaData.arguments.arguments[0].end
+                });
+                return ApplyNodeResult.NotAppliedSemanticError;
+        }
+        for (let i = 1; i < metaData.arguments.arguments.length; i++) {
+            const groupSize = metaData.arguments.arguments[i].value;
+            if (groupSize < 1) {
+                importer.addSemanticDiagnostic({
+                    code: AlphaTexDiagnosticCode.AT209,
+                    message: `Value is out of valid range. Allowed range: >0, Actual Value: ${durationValue}`,
+                    severity: AlphaTexDiagnosticsSeverity.Error,
+                    start: metaData.arguments.arguments[i].start,
+                    end: metaData.arguments.arguments[i].end
+                });
+                return ApplyNodeResult.NotAppliedSemanticError;
+            }
+            groupSizes.push(metaData.arguments.arguments[i].value);
+        }
+        if (!masterBar.beamingRules) {
+            masterBar.beamingRules = new BeamingRules();
+        }
+        masterBar.beamingRules.groups.set(duration, groupSizes);
+        return ApplyNodeResult.Applied;
+    }
     static _handleAccidentalMode(importer, args) {
         const accidentalMode = AlphaTex1LanguageHandler._parseEnumValue(importer, args, 'accidental mode', AlphaTex1EnumMappings.alphaTexAccidentalMode);
         if (accidentalMode === undefined) {
@@ -15032,6 +15277,15 @@ class AlphaTex1LanguageHandler {
                 ])));
             }
         }
+        if (masterBar.beamingRules) {
+            for (const [k, v] of masterBar.beamingRules.groups) {
+                const args = Atnf.args([Atnf.number(k)], true);
+                for (const i of v) {
+                    args.arguments.push(Atnf.number(i));
+                }
+                nodes.push(Atnf.meta('beaming', args));
+            }
+        }
         if ((masterBar.index > 0 && masterBar.tripletFeel !== masterBar.previousMasterBar?.tripletFeel) ||
             (masterBar.index === 0 && masterBar.tripletFeel !== TripletFeel.NoTripletFeel)) {
             nodes.push(Atnf.identMeta('tf', AlphaTex1EnumMappings.tripletFeelReversed.get(masterBar.tripletFeel)));
@@ -23032,6 +23286,8 @@ class GpifParser {
         }
     }
     _parseMasterBarXProperties(masterBar, node) {
+        let beamingRuleDuration = Number.NaN;
+        let beamingRuleGroups = undefined;
         for (const c of node.childElements()) {
             switch (c.localName) {
                 case 'XProperty':
@@ -23040,10 +23296,32 @@ class GpifParser {
                         case '1124073984':
                             masterBar.displayScale = GpifParser._parseFloatSafe(c.findChildElement('Double')?.innerText, 1);
                             break;
+                        case '1124139010':
+                            beamingRuleDuration = GpifParser._parseIntSafe(c.findChildElement('Int')?.innerText, Number.NaN);
+                            break;
+                        default:
+                            const idNumeric = GpifParser._parseIntSafe(id, 0);
+                            if (idNumeric >= 1124139264 && idNumeric <= 1124139295) {
+                                const groupIndex = idNumeric - 1124139264;
+                                const groupSize = GpifParser._parseIntSafe(c.findChildElement('Int')?.innerText, Number.NaN);
+                                if (beamingRuleGroups === undefined) {
+                                    beamingRuleGroups = [];
+                                }
+                                while (beamingRuleGroups.length < groupIndex + 1) {
+                                    beamingRuleGroups.push(0);
+                                }
+                                beamingRuleGroups[groupIndex] = groupSize;
+                            }
+                            break;
                     }
                     break;
             }
         }
+        if (!Number.isNaN(beamingRuleDuration) && beamingRuleGroups) {
+            const rules = new BeamingRules();
+            rules.groups.set(beamingRuleDuration, beamingRuleGroups);
+            masterBar.beamingRules = rules;
+        }
     }
     _parseBeatProperties(node, beat) {
         let isWhammy = false;
@@ -36579,6 +36857,43 @@ class JsonHelper {
     }
 }
 
+/**
+ * @internal
+ */
+class BeamingRulesSerializer {
+    static fromJson(obj, m) {
+        if (!m) {
+            return;
+        }
+        JsonHelper.forEach(m, (v, k) => BeamingRulesSerializer.setProperty(obj, k, v));
+    }
+    static toJson(obj) {
+        if (!obj) {
+            return null;
+        }
+        const o = new Map();
+        {
+            const m = new Map();
+            o.set("groups", m);
+            for (const [k, v] of obj.groups) {
+                m.set(k.toString(), v);
+            }
+        }
+        return o;
+    }
+    static setProperty(obj, property, v) {
+        switch (property) {
+            case "groups":
+                obj.groups = new Map();
+                JsonHelper.forEach(v, (v, k) => {
+                    obj.groups.set(JsonHelper.parseEnum(k, Duration), v);
+                });
+                return true;
+        }
+        return false;
+    }
+}
+
 /**
  * @internal
  */
@@ -36757,6 +37072,9 @@ class MasterBarSerializer {
         o.set("timesignaturenumerator", obj.timeSignatureNumerator);
         o.set("timesignaturedenominator", obj.timeSignatureDenominator);
         o.set("timesignaturecommon", obj.timeSignatureCommon);
+        if (obj.beamingRules) {
+            o.set("beamingrules", BeamingRulesSerializer.toJson(obj.beamingRules));
+        }
         o.set("isfreetime", obj.isFreeTime);
         o.set("tripletfeel", obj.tripletFeel);
         if (obj.section) {
@@ -36809,6 +37127,15 @@ class MasterBarSerializer {
             case "timesignaturecommon":
                 obj.timeSignatureCommon = v;
                 return true;
+            case "beamingrules":
+                if (v) {
+                    obj.beamingRules = new BeamingRules();
+                    BeamingRulesSerializer.fromJson(obj.beamingRules, v);
+                }
+                else {
+                    obj.beamingRules = undefined;
+                }
+                return true;
             case "isfreetime":
                 obj.isFreeTime = v;
                 return true;
@@ -61467,6 +61794,7 @@ class BeamingHelperDrawInfo {
 class BeamingHelper {
     _staff;
     _renderer;
+    _beamingRuleLookup;
     voice = null;
     beats = [];
     shortestDuration = Duration.QuadrupleWhole;
@@ -61500,10 +61828,11 @@ class BeamingHelper {
     static beatHasFlag(beat) {
         return (!beat.deadSlapped && !beat.isRest && (beat.duration > Duration.Quarter || beat.graceType !== GraceType.None));
     }
-    constructor(staff, renderer) {
+    constructor(staff, renderer, beamingRuleLookup) {
         this._staff = staff;
         this._renderer = renderer;
         this.beats = [];
+        this._beamingRuleLookup = beamingRuleLookup;
     }
     alignWithBeats() {
         for (const v of this.drawingInfos.values()) {
@@ -61558,7 +61887,7 @@ class BeamingHelper {
             switch (this.beats[this.beats.length - 1].beamingMode) {
                 case BeatBeamingMode.Auto:
                 case BeatBeamingMode.ForceSplitOnSecondaryToNext:
-                    add = BeamingHelper._canJoin(this.beats[this.beats.length - 1], beat);
+                    add = this._canJoin(this.beats[this.beats.length - 1], beat);
                     break;
                 case BeatBeamingMode.ForceSplitToNext:
                     add = false;
@@ -61630,8 +61959,7 @@ class BeamingHelper {
             this._highestNoteCompareValueInHelper = highestValueForNote;
         }
     }
-    // TODO: Check if this beaming is really correct, I'm not sure if we are connecting beats correctly
-    static _canJoin(b1, b2) {
+    _canJoin(b1, b2) {
         // is this a voice we can join with?
         if (!b1 ||
             !b2 ||
@@ -61669,19 +61997,10 @@ class BeamingHelper {
                 return true;
             }
         }
-        // TODO: create more rules for automatic beaming
-        let divisionLength = MidiUtils.QuarterTime;
-        switch (m1.masterBar.timeSignatureDenominator) {
-            case 8:
-                if (m1.masterBar.timeSignatureNumerator % 3 === 0) {
-                    divisionLength += (MidiUtils.QuarterTime / 2) | 0;
-                }
-                break;
-        }
-        // check if they are on the same division
-        const division1 = ((divisionLength + start1) / divisionLength) | 0 | 0;
-        const division2 = ((divisionLength + start2) / divisionLength) | 0 | 0;
-        return division1 === division2;
+        // check if they are on the same group as per rule definitions
+        const groupId1 = this._beamingRuleLookup.calculateGroupIndex(start1);
+        const groupId2 = this._beamingRuleLookup.calculateGroupIndex(start2);
+        return groupId1 === groupId2;
     }
     static _canJoinDuration(d) {
         switch (d) {
@@ -61848,6 +62167,61 @@ class BarCollisionHelper {
     }
 }
 
+/**
+ * @internal
+ */
+class BeamingRuleLookup {
+    _division = 0;
+    _slots = [];
+    _barDuration;
+    constructor(barDuration, division, slots) {
+        this._division = division;
+        this._slots = slots;
+        this._barDuration = barDuration;
+    }
+    calculateGroupIndex(beatStartTime) {
+        // no slots -> all have their own group based (use the start time as index)
+        if (this._slots.length === 0) {
+            return beatStartTime;
+        }
+        // rollover within the bar.
+        beatStartTime = beatStartTime % this._barDuration;
+        const slotIndex = Math.floor(beatStartTime / this._division);
+        return this._slots[slotIndex];
+    }
+    static build(masterBar, ruleDuration, ruleGroups) {
+        const totalDuration = masterBar.calculateDuration(false);
+        const division = MidiUtils.toTicks(ruleDuration);
+        const slotCount = totalDuration / division;
+        // should only happen in case of improper data.
+        if (slotCount < 0 || ruleGroups.length === 0) {
+            return new BeamingRuleLookup(0, 0, []);
+        }
+        let groupIndex = 0;
+        let remainingSlots = ruleGroups[groupIndex];
+        const slots = [];
+        for (let i = 0; i < slotCount; i++) {
+            if (groupIndex < ruleGroups.length) {
+                slots.push(groupIndex);
+                remainingSlots--;
+                if (remainingSlots <= 0) {
+                    groupIndex++;
+                    if (groupIndex < ruleGroups.length) {
+                        remainingSlots = ruleGroups[groupIndex];
+                    }
+                }
+            }
+            else {
+                // no groups defined for the remaining slots: all slots are treated
+                // as unjoined
+                slots.push(groupIndex);
+                groupIndex++;
+            }
+        }
+        return new BeamingRuleLookup(totalDuration, division, slots);
+    }
+}
+
 /**
  * @internal
  */
@@ -61864,6 +62238,19 @@ class BarHelpers {
     initialize() {
         const barRenderer = this._renderer;
         const bar = this._renderer.bar;
+        const masterBar = bar.masterBar;
+        const beamingRules = masterBar.actualBeamingRules ?? BarHelpers._findOrBuildDefaultBeamingRules(masterBar);
+        const rule = beamingRules.findRule(bar.shortestDuration);
+        // NOTE: moste rules have only one group definition, so its better to reuse the unique id
+        // than compute a potentially shorter id here.
+        const key = `beaming_${beamingRules.uniqueId}_${rule[0]}`;
+        let beamingRuleLookup = this._renderer.scoreRenderer.layout.beamingRuleLookups.has(key)
+            ? this._renderer.scoreRenderer.layout.beamingRuleLookups.get(key)
+            : undefined;
+        if (!beamingRuleLookup) {
+            beamingRuleLookup = BeamingRuleLookup.build(masterBar, rule[0], rule[1]);
+            this._renderer.scoreRenderer.layout.beamingRuleLookups.set(key, beamingRuleLookup);
+        }
         let currentBeamHelper = null;
         let currentGraceBeamHelper = null;
         for (let i = 0, j = bar.voices.length; i < j; i++) {
@@ -61889,7 +62276,7 @@ class BarHelpers {
                         helperForBeat.finish();
                     }
                     // if not possible, create the next beaming helper
-                    helperForBeat = new BeamingHelper(bar.staff, barRenderer);
+                    helperForBeat = new BeamingHelper(bar.staff, barRenderer, beamingRuleLookup);
                     helperForBeat.preferredBeamDirection = this.preferredBeamDirection;
                     helperForBeat.checkBeat(b);
                     if (b.graceType !== GraceType.None) {
@@ -61912,6 +62299,69 @@ class BarHelpers {
             currentGraceBeamHelper = null;
         }
     }
+    static _defaultBeamingRules;
+    static _findOrBuildDefaultBeamingRules(masterBar) {
+        let defaultBeamingRules = BarHelpers._defaultBeamingRules;
+        if (!defaultBeamingRules) {
+            defaultBeamingRules = new Map([
+                BeamingRules.createSimple(2, 16, Duration.Sixteenth, [1, 1]),
+                BeamingRules.createSimple(1, 8, Duration.Eighth, [1]),
+                BeamingRules.createSimple(1, 4, Duration.Quarter, [1]),
+                BeamingRules.createSimple(3, 16, Duration.Sixteenth, [3]),
+                BeamingRules.createSimple(4, 16, Duration.Sixteenth, [2, 2]),
+                BeamingRules.createSimple(2, 8, Duration.Eighth, [1, 1]),
+                BeamingRules.createSimple(5, 16, Duration.Sixteenth, [3, 2]),
+                BeamingRules.createSimple(6, 16, Duration.Sixteenth, [3, 3]),
+                BeamingRules.createSimple(3, 8, Duration.Eighth, [3]),
+                BeamingRules.createSimple(4, 8, Duration.Eighth, [2, 2]),
+                BeamingRules.createSimple(2, 4, Duration.Quarter, [1, 1]),
+                BeamingRules.createSimple(9, 16, Duration.Sixteenth, [3, 3, 3]),
+                BeamingRules.createSimple(5, 8, Duration.Eighth, [3, 2]),
+                BeamingRules.createSimple(12, 16, Duration.Sixteenth, [3, 3, 3, 3]),
+                BeamingRules.createSimple(6, 8, Duration.Eighth, [3, 3, 3]),
+                BeamingRules.createSimple(3, 4, Duration.Quarter, [1, 1, 1]),
+                BeamingRules.createSimple(7, 8, Duration.Eighth, [4, 3]),
+                BeamingRules.createSimple(8, 8, Duration.Eighth, [3, 3, 2]),
+                BeamingRules.createSimple(4, 4, Duration.Quarter, [1, 1, 1, 1]),
+                BeamingRules.createSimple(9, 8, Duration.Eighth, [3, 3, 3]),
+                BeamingRules.createSimple(10, 8, Duration.Eighth, [4, 3, 3]),
+                BeamingRules.createSimple(5, 4, Duration.Quarter, [1, 1, 1, 1, 1]),
+                BeamingRules.createSimple(12, 8, Duration.Eighth, [3, 3, 3, 3]),
+                BeamingRules.createSimple(6, 4, Duration.Quarter, [1, 1, 1, 1, 1, 1]),
+                BeamingRules.createSimple(15, 8, Duration.Eighth, [3, 3, 3, 3, 3, 3]),
+                BeamingRules.createSimple(8, 4, Duration.Quarter, [1, 1, 1, 1, 1, 1, 1, 1]),
+                BeamingRules.createSimple(18, 8, Duration.Eighth, [3, 3, 3, 3, 3, 3])
+            ].map(r => [`${r.timeSignatureNumerator}_${r.timeSignatureDenominator}`, r]));
+            BarHelpers._defaultBeamingRules = defaultBeamingRules;
+        }
+        const key = `${masterBar.timeSignatureNumerator}_${masterBar.timeSignatureDenominator}`;
+        if (defaultBeamingRules.has(key)) {
+            return defaultBeamingRules.get(key);
+        }
+        // NOTE: this is the old alphaTab logic how we used to beamed bars.
+        // we either group in quarters, or in 3x8ths depending on the key signature
+        let divisionLength = MidiUtils.QuarterTime;
+        switch (masterBar.timeSignatureDenominator) {
+            case 8:
+                if (masterBar.timeSignatureNumerator % 3 === 0) {
+                    divisionLength += (MidiUtils.QuarterTime / 2) | 0;
+                }
+                break;
+        }
+        const numberOfDivisions = Math.ceil(masterBar.calculateDuration(false) / divisionLength);
+        const notesPerDivision = (divisionLength / MidiUtils.QuarterTime) * 2;
+        const fallback = new BeamingRules();
+        const groups = [];
+        for (let i = 0; i < numberOfDivisions; i++) {
+            groups.push(notesPerDivision);
+        }
+        fallback.groups.set(Duration.Eighth, groups);
+        fallback.timeSignatureNumerator = masterBar.timeSignatureNumerator;
+        fallback.timeSignatureDenominator = masterBar.timeSignatureDenominator;
+        fallback.finish();
+        defaultBeamingRules.set(key, fallback);
+        return fallback;
+    }
     getBeamingHelperForBeat(beat) {
         return this._beamHelperLookup.has(beat.id) ? this._beamHelperLookup.get(beat.id) : undefined;
     }
@@ -65844,6 +66294,7 @@ class ScoreLayout {
         this.renderer = renderer;
     }
     slurRegistry = new SlurRegistry();
+    beamingRuleLookups = new Map();
     resize() {
         this._lazyPartials.clear();
         this.slurRegistry.clear();
@@ -65852,6 +66303,7 @@ class ScoreLayout {
     layoutAndRender() {
         this._lazyPartials.clear();
         this.slurRegistry.clear();
+        this.beamingRuleLookups.clear();
         this._barRendererLookup.clear();
         this.profile = Environment.staveProfiles.get(this.renderer.settings.display.staveProfile);
         const score = this.renderer.score;
@@ -78039,6 +78491,9 @@ class GpifWriter {
         key.addElement('Sharps').innerText = 'Sharps';
         masterBarNode.addElement('Time').innerText =
             `${masterBar.timeSignatureNumerator}/${masterBar.timeSignatureDenominator}`;
+        if (masterBar.actualBeamingRules) {
+            this._writeBarXProperties(masterBarNode, masterBar);
+        }
         if (masterBar.isFreeTime) {
             masterBarNode.addElement('FreeTime');
         }
@@ -78148,6 +78603,29 @@ class GpifWriter {
         }
         this._writeFermatas(masterBarNode, masterBar);
     }
+    _writeBarXProperties(masterBarNode, masterBar) {
+        const properties = masterBarNode.addElement('XProperties');
+        const beamingRules = masterBar.actualBeamingRules;
+        if (beamingRules) {
+            // prefer 8th note rule (that's what GP mostly has)
+            const rule = beamingRules.findRule(Duration.Eighth);
+            // NOTE: it's not clear if guitar pro supports quarter rules
+            // for that case we better convert this to an "8th" note rule.
+            let durationProp = rule[0];
+            let groupSizeFactor = 1;
+            if (rule[0] === Duration.Quarter) {
+                durationProp = 8;
+                groupSizeFactor = 2;
+            }
+            this._writeSimpleXPropertyNode(properties, '1124139010', 'Int', durationProp.toString());
+            const startGroupid = 1124139264;
+            let i = 0;
+            while (i < rule[1].length) {
+                this._writeSimpleXPropertyNode(properties, (startGroupid + i).toString(), 'Int', (rule[1][i] * groupSizeFactor).toString());
+                i++;
+            }
+        }
+    }
     _writeFermatas(parent, masterBar) {
         const fermataCount = masterBar.fermata?.size ?? 0;
         if (fermataCount === 0) {