feat: displaced note heads for multiple voices

packages/alphatab/.env

@@ -1,2 +1,3 @@
 FORCE_COLOR=1
 NODE_OPTIONS=--expose-gc
+UPDATE_SNAPSHOT=true

packages/alphatab/src/EngravingSettings.ts

@@ -2,8 +2,7 @@ import { EngravingSettingsCloner } from '@coderline/alphatab/generated/Engraving
 import { JsonHelper } from '@coderline/alphatab/io/JsonHelper';
 import { Logger } from '@coderline/alphatab/Logger';
 import { Duration } from '@coderline/alphatab/model/Duration';
-import { ModelUtils } from '@coderline/alphatab/model/ModelUtils';
-import { MusicFontSymbol } from '@coderline/alphatab/model/MusicFontSymbol';
+import { MusicFontSymbol, MusicFontSymbolLookup } from '@coderline/alphatab/model/MusicFontSymbol';
 import type { SmuflMetadata } from '@coderline/alphatab/SmuflMetadata';
 
 /**
@@ -53,6 +52,12 @@ export class EngravingStemInfo {
 export class EngravingSettings {
     private static _bravuraDefaults?: EngravingSettings;
 
+    // NOTE: configurable in future?
+    /**
+     * @internal
+     */
+    public static readonly GraceScale: number = 0.75;
+
     /**
      * A {@link EngravingSettings} copy filled with the settings of the Bravura font used by default in alphaTab.
      */
@@ -431,7 +436,7 @@ export class EngravingSettings {
             MusicFontSymbol.NoteheadNull
         ]);
 
-        for (const symbol of ModelUtils.getAllMusicFontSymbols()) {
+        for (const symbol of MusicFontSymbolLookup.getAllMusicFontSymbols()) {
             if (!handledSymbols.has(symbol)) {
                 if (!ignoredSymbols.has(symbol)) {
                     Logger.warning(
@@ -498,6 +503,7 @@ export class EngravingSettings {
         this.tripletFeelBracketPadding = 0.2 * this.oneStaffSpace;
         this.accidentalPadding = 0.1 * this.oneStaffSpace;
         this.preBeatGlyphSpacing = 0.5 * this.oneStaffSpace;
+        this.multiVoiceDisplacedNoteHeadSpacing = 0.2 * this.oneStaffSpace;
 
         this.tuningGlyphStringRowPadding = 0.2 * this.oneStaffSpace;
     }
@@ -554,21 +560,20 @@ export class EngravingSettings {
     public lineRangedGlyphDashSize = 0;
 
     /**
-     * The padding between effects and glyphs placed before the note heads, e.g. accidentals or brushes 
+     * The padding between effects and glyphs placed before the note heads, e.g. accidentals or brushes
      */
     public preNoteEffectPadding = 0;
 
     /**
-     * The padding between effects and glyphs placed after the note heads, e.g. slides or bends 
+     * The padding between effects and glyphs placed after the note heads, e.g. slides or bends
      */
     public postNoteEffectPadding = 0;
 
     /**
-     * The padding between effects and glyphs placed above/blow the note heads e.g. staccato 
+     * The padding between effects and glyphs placed above/blow the note heads e.g. staccato
      */
     public onNoteEffectPadding = 0;
 
-
     /**
      * The padding between the circles around string numbers.
      */
@@ -600,7 +605,7 @@ export class EngravingSettings {
     public tieHeight = 0;
 
     /**
-     * The padding between the border and text of beat timers. 
+     * The padding between the border and text of beat timers.
      */
     public beatTimerPadding = 0;
 
@@ -630,7 +635,7 @@ export class EngravingSettings {
     public tabWhammyTextPadding = 0;
 
     /**
-     * The height applied per half-note whammy. 
+     * The height applied per half-note whammy.
      */
     public tabWhammyPerHalfHeight = 0;
 
@@ -658,15 +663,15 @@ export class EngravingSettings {
      * The size of the dashes on bends (e.g. on holds)
      */
     public tabBendDashSize = 0;
-    
+
     /**
      * The additional padding between the staff and the point
      * where bend values are calculated from.
      */
     public tabBendStaffPadding = 0;
-    
+
     /**
-     * The height applied per quarter-note. 
+     * The height applied per quarter-note.
      */
     public tabBendPerValueHeight = 0;
 
@@ -714,7 +719,7 @@ export class EngravingSettings {
     public chordDiagramLineWidth = 0;
 
     /**
-     * The padding between the bracket lines and numbers of tuplets 
+     * The padding between the bracket lines and numbers of tuplets
      */
     public tripletFeelBracketPadding = 0;
 
@@ -753,6 +758,12 @@ export class EngravingSettings {
      */
     public directionsScale = 0.6;
 
+    /**
+     * The spacing between displaced displaced note heads 
+     * in case of multi-voice note head overlaps. 
+     */
+    public multiVoiceDisplacedNoteHeadSpacing = 0;
+
     // Idea: maybe we can encode and pack this large metadata into a more compact format (e.g. BSON or a custom binary blob?)
     // This metadata below is updated automatically from the bravura_metadata.json via npm script
 

packages/alphatab/src/Environment.ts

@@ -831,4 +831,17 @@ export class Environment {
     public static quoteJsonString(text: string) {
         return JSON.stringify(text);
     }
+
+    /**
+     * @internal
+     * @target web
+     * @partial
+     */
+    public static sortDescending(array: number[]) {
+        // java is a joke:
+        // no primitive sorting of arrays with custom comparer in 2025
+        // so we need to declare this specific helper function and implement it in Kotlin ourselves.
+        array.sort((a, b) => b - a);
+    }
+
 }

packages/alphatab/src/generated/EngravingSettingsCloner.ts

@@ -92,6 +92,7 @@ export class EngravingSettingsCloner {
         clone.tuningGlyphStringColumnScale = original.tuningGlyphStringColumnScale;
         clone.tuningGlyphStringRowPadding = original.tuningGlyphStringRowPadding;
         clone.directionsScale = original.directionsScale;
+        clone.multiVoiceDisplacedNoteHeadSpacing = original.multiVoiceDisplacedNoteHeadSpacing;
         return clone;
     }
 }

packages/alphatab/src/generated/EngravingSettingsJson.ts

@@ -395,4 +395,9 @@ export interface EngravingSettingsJson {
      * The relative scale of any directions glyphs drawn like coda or segno.
      */
     directionsScale?: number;
+    /**
+     * The spacing between displaced displaced note heads
+     * in case of multi-voice note head overlaps.
+     */
+    multiVoiceDisplacedNoteHeadSpacing?: number;
 }

packages/alphatab/src/generated/EngravingSettingsSerializer.ts

@@ -154,6 +154,7 @@ export class EngravingSettingsSerializer {
         o.set("tuningglyphstringcolumnscale", obj.tuningGlyphStringColumnScale);
         o.set("tuningglyphstringrowpadding", obj.tuningGlyphStringRowPadding);
         o.set("directionsscale", obj.directionsScale);
+        o.set("multivoicedisplacednoteheadspacing", obj.multiVoiceDisplacedNoteHeadSpacing);
         return o;
     }
     public static setProperty(obj: EngravingSettings, property: string, v: unknown): boolean {
@@ -432,6 +433,9 @@ export class EngravingSettingsSerializer {
             case "directionsscale":
                 obj.directionsScale = v! as number;
                 return true;
+            case "multivoicedisplacednoteheadspacing":
+                obj.multiVoiceDisplacedNoteHeadSpacing = v! as number;
+                return true;
         }
         return false;
     }

packages/alphatab/src/importer/alphaTex/AlphaTex1LanguageHandler.ts

@@ -278,7 +278,7 @@ export class AlphaTex1LanguageHandler implements IAlphaTexLanguageImportHandler
 
         const types = lookup.get(tag);
         if (!types) {
-            if (args) {
+            if (args && args.arguments.length > 0) {
                 importer.addSemanticDiagnostic({
                     code: AlphaTexDiagnosticCode.AT300,
                     message: `Expected no arguments, but found some.`,

packages/alphatab/src/importer/alphaTex/AlphaTex1MetaDataReader.ts

@@ -47,6 +47,19 @@ export class AlphaTex1MetaDataReader implements IAlphaTexMetaDataReader {
         AlphaTexNodeType.Number
     ]);
 
+    public hasMetaDataArguments(metaData: AlphaTexMetaDataTagNode): boolean {
+        const tag = metaData.tag.text.toLowerCase();
+        for (const lookup of AlphaTex1LanguageDefinitions.metaDataSignatures) {
+            if (lookup.has(tag)) {
+                const types = lookup.get(tag);
+                return types !== null;
+            }
+        }
+
+        // unknown meta -> assume args exist
+        return true;
+    }
+
     public readMetaDataArguments(
         parser: AlphaTexParser,
         metaData: AlphaTexMetaDataTagNode
@@ -83,7 +96,10 @@ export class AlphaTex1MetaDataReader implements IAlphaTexMetaDataReader {
         if (!AlphaTex1LanguageDefinitions.metaDataProperties.has(tag)) {
             return undefined;
         }
-        const props = AlphaTex1LanguageDefinitions.metaDataProperties.get(tag)!;
+        const props = AlphaTex1LanguageDefinitions.metaDataProperties.get(tag);
+        if (!props) {
+            return this._readPropertyArguments(parser, [], property);
+        }
         return this._readPropertyArguments(parser, [props], property);
     }
 

packages/alphatab/src/importer/alphaTex/AlphaTexParser.ts

@@ -67,7 +67,7 @@ export class AlphaTexParser {
     /**
      * The parsing mode.
      */
-    public mode:AlphaTexParseMode = AlphaTexParseMode.ForModelImport;
+    public mode: AlphaTexParseMode = AlphaTexParseMode.ForModelImport;
 
     public get lexerDiagnostics(): AlphaTexDiagnosticBag {
         return this.lexer.lexerDiagnostics;
@@ -509,7 +509,6 @@ export class AlphaTexParser {
 
     private static readonly _allowValuesAfterProperties = new Set<string>(['chord']);
 
-
     private _metaData(metaDataList: AlphaTexMetaDataNode[]) {
         const tag = this.lexer.peekToken();
         if (!tag || tag.nodeType !== AlphaTexNodeType.Tag) {
@@ -558,17 +557,19 @@ export class AlphaTexParser {
                     }
                 }
             } else {
-                metaData.arguments = this.argumentList();
-                if (!metaData.arguments) {
-                    metaData.arguments = this._metaDataReader.readMetaDataArguments(this, metaData.tag);
-                    if (metaData.arguments && metaData.arguments.arguments.length > 1) {
-                        this.addParserDiagnostic({
-                            code: AlphaTexDiagnosticCode.AT301,
-                            message: `Metadata arguments should be wrapped into parenthesis.`,
-                            severity: AlphaTexDiagnosticsSeverity.Warning,
-                            start: metaData.arguments?.start ?? metaData.start,
-                            end: metaData.arguments?.end ?? metaData.end
-                        });
+                if (this._metaDataReader.hasMetaDataArguments(metaData.tag)) {
+                    metaData.arguments = this.argumentList();
+                    if (!metaData.arguments) {
+                        metaData.arguments = this._metaDataReader.readMetaDataArguments(this, metaData.tag);
+                        if (metaData.arguments && metaData.arguments.arguments.length > 1) {
+                            this.addParserDiagnostic({
+                                code: AlphaTexDiagnosticCode.AT301,
+                                message: `Metadata arguments should be wrapped into parenthesis.`,
+                                severity: AlphaTexDiagnosticsSeverity.Warning,
+                                start: metaData.arguments?.start ?? metaData.start,
+                                end: metaData.arguments?.end ?? metaData.end
+                            });
+                        }
                     }
                 }
 

packages/alphatab/src/importer/alphaTex/IAlphaTexMetaDataReader.ts

@@ -1,14 +1,15 @@
 import type {
+    AlphaTexArgumentList, 
     AlphaTexMetaDataTagNode,
-    AlphaTexPropertyNode,
-    AlphaTexArgumentList
+    AlphaTexPropertyNode
 } from '@coderline/alphatab/importer/alphaTex/AlphaTexAst';
 import type { AlphaTexParser } from '@coderline/alphatab/importer/alphaTex/AlphaTexParser';
 
 /**
  * @internal
  */
 export interface IAlphaTexMetaDataReader {
+    hasMetaDataArguments(metaData: AlphaTexMetaDataTagNode): boolean;
     readMetaDataArguments(parser: AlphaTexParser, metaData: AlphaTexMetaDataTagNode): AlphaTexArgumentList | undefined;
 
     readMetaDataPropertyArguments(

packages/alphatab/src/model/Beat.ts

@@ -1173,7 +1173,6 @@ export class Beat {
         return this.noteStringLookup.has(noteString);
     }
 
-    // TODO: can be likely eliminated
     public getNoteWithRealValue(noteRealValue: number): Note | null {
         if (this.noteValueLookup.has(noteRealValue)) {
             return this.noteValueLookup.get(noteRealValue)!;

packages/alphatab/src/model/ModelUtils.ts

@@ -1,17 +1,16 @@
+import { AccidentalType } from '@coderline/alphatab/model/AccidentalType';
+import { Automation, AutomationType } from '@coderline/alphatab/model/Automation';
+import { Bar } from '@coderline/alphatab/model/Bar';
 import { Beat } from '@coderline/alphatab/model/Beat';
 import type { Duration } from '@coderline/alphatab/model/Duration';
-import { HeaderFooterStyle, type Score, ScoreStyle, type ScoreSubElement } from '@coderline/alphatab/model/Score';
-import type { Settings } from '@coderline/alphatab/Settings';
-import { NoteAccidentalMode } from '@coderline/alphatab/model/NoteAccidentalMode';
+import type { KeySignature } from '@coderline/alphatab/model/KeySignature';
 import { MasterBar } from '@coderline/alphatab/model/MasterBar';
+import { NoteAccidentalMode } from '@coderline/alphatab/model/NoteAccidentalMode';
+import { HeaderFooterStyle, type Score, ScoreStyle, type ScoreSubElement } from '@coderline/alphatab/model/Score';
 import type { Track } from '@coderline/alphatab/model/Track';
-import { SynthConstants } from '@coderline/alphatab/synth/SynthConstants';
-import { Bar } from '@coderline/alphatab/model/Bar';
 import { Voice } from '@coderline/alphatab/model/Voice';
-import { Automation, AutomationType } from '@coderline/alphatab/model/Automation';
-import { MusicFontSymbol } from '@coderline/alphatab/model/MusicFontSymbol';
-import type { KeySignature } from '@coderline/alphatab/model/KeySignature';
-import { AccidentalType } from '@coderline/alphatab/model/AccidentalType';
+import type { Settings } from '@coderline/alphatab/Settings';
+import { SynthConstants } from '@coderline/alphatab/synth/SynthConstants';
 
 /**
  * @internal
@@ -671,22 +670,6 @@ export class ModelUtils {
             masterBar.previousMasterBar!.nextMasterBar = null;
         }
     }
-
-    private static _allMusicFontSymbols: MusicFontSymbol[] = [];
-
-    /**
-     * Gets a list of all music font symbols used in alphaTab.
-     */
-    public static getAllMusicFontSymbols(): MusicFontSymbol[] {
-        if (ModelUtils._allMusicFontSymbols.length === 0) {
-            ModelUtils._allMusicFontSymbols = Object.values(MusicFontSymbol)
-                .filter<any>((k: any) => typeof k === 'number')
-                .map(v => v as number as MusicFontSymbol) as MusicFontSymbol[];
-        }
-
-        return ModelUtils._allMusicFontSymbols;
-    }
-
     /**
      * Lists the display transpositions for some known midi instruments.
      * It is a common practice to transpose the standard notation for instruments like guitars.

packages/alphatab/src/model/MusicFontSymbol.ts

@@ -346,3 +346,38 @@ export enum MusicFontSymbol {
     FingeringALower = 0xed1b,
     FingeringCLower = 0xed1c
 }
+
+/**
+ * @internal
+ */
+export class MusicFontSymbolLookup {
+    private static _allMusicFontSymbols: MusicFontSymbol[] = [];
+    private static readonly _blackNoteHeadGlyphs = new Set<MusicFontSymbol>();
+
+    private static _initialize() {
+        const all = MusicFontSymbolLookup._allMusicFontSymbols;
+        if (all.length === 0) {
+            for (const v of Object.values(MusicFontSymbol).filter<any>((k: any) => typeof k === 'number')) {
+                const symbol = v as number as MusicFontSymbol;
+                all.push(symbol);
+                const name = MusicFontSymbol[symbol].toLowerCase();
+                if (name.endsWith('black')) {
+                    MusicFontSymbolLookup._blackNoteHeadGlyphs.add(symbol);
+                }
+            }
+        }
+    }
+
+    /**
+     * Gets a list of all music font symbols used in alphaTab.
+     */
+    public static getAllMusicFontSymbols(): MusicFontSymbol[] {
+        MusicFontSymbolLookup._initialize();
+        return MusicFontSymbolLookup._allMusicFontSymbols;
+    }
+
+    public static isBlackNoteHead(glph: MusicFontSymbol): boolean {
+        MusicFontSymbolLookup._initialize();
+        return MusicFontSymbolLookup._blackNoteHeadGlyphs.has(glph);
+    }
+}

packages/alphatab/src/model/Score.ts

@@ -432,6 +432,13 @@ export class Score {
         for (let i: number = 0, j: number = this.tracks.length; i < j; i++) {
             this.tracks[i].finish(settings, sharedDataBag);
         }
+
+        // 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();
+            }
+        }
     }
 
     /**