feat(rendering): add per-beat rest display position via beat.restDisplayTone, beat.restDisplayOctave

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

@@ -39,6 +39,8 @@ export class BeatCloner {
         clone.text = original.text;
         clone.slashed = original.slashed;
         clone.deadSlapped = original.deadSlapped;
+        clone.restDisplayTone = original.restDisplayTone;
+        clone.restDisplayOctave = original.restDisplayOctave;
         clone.brushType = original.brushType;
         clone.brushDuration = original.brushDuration;
         clone.tupletDenominator = original.tupletDenominator;

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

@@ -64,6 +64,8 @@ export class BeatSerializer {
         o.set("text", obj.text);
         o.set("slashed", obj.slashed);
         o.set("deadslapped", obj.deadSlapped);
+        o.set("restdisplaytone", obj.restDisplayTone);
+        o.set("restdisplayoctave", obj.restDisplayOctave);
         o.set("brushtype", obj.brushType as number);
         o.set("brushduration", obj.brushDuration);
         o.set("tupletdenominator", obj.tupletDenominator);
@@ -165,6 +167,12 @@ export class BeatSerializer {
             case "deadslapped":
                 obj.deadSlapped = v! as boolean;
                 return true;
+            case "restdisplaytone":
+                obj.restDisplayTone = v !== null && v !== undefined ? v as number : -1;
+                return true;
+            case "restdisplayoctave":
+                obj.restDisplayOctave = v! as number;
+                return true;
             case "brushtype":
                 obj.brushType = JsonHelper.parseEnum<BrushType>(v, BrushType)!;
                 return true;

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

@@ -664,6 +664,7 @@ export class AlphaTex1LanguageDefinitions {
             ]
         ],
         ['txt', [[[[17, 10], 0]]]],
+        ['restdisplaypitch', [[[[10, 17], 0]]]],
         [
             'lyrics',
             [

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

@@ -1616,6 +1616,23 @@ export class AlphaTex1LanguageHandler implements IAlphaTexLanguageImportHandler
             case 'txt':
                 beat.text = (p.arguments!.arguments[0] as AlphaTexTextNode).text;
                 return ApplyNodeResult.Applied;
+            case 'restdisplaypitch': {
+                const tuning = ModelUtils.parseTuning((p.arguments!.arguments[0] as AlphaTexTextNode).text);
+                if (tuning !== null) {
+                    beat.restDisplayTone = tuning.tone.noteValue;
+                    beat.restDisplayOctave = tuning.octave - 1;
+                } else {
+                    importer.addSemanticDiagnostic({
+                        code: AlphaTexDiagnosticCode.AT212,
+                        message: `Invalid pitch value '${(p.arguments!.arguments[0] as AlphaTexTextNode).text}', expected format like 'C5' or 'G4'`,
+                        severity: AlphaTexDiagnosticsSeverity.Error,
+                        start: p.arguments!.arguments[0].start,
+                        end: p.arguments!.arguments[0].end
+                    });
+                    return ApplyNodeResult.NotAppliedSemanticError;
+                }
+                return ApplyNodeResult.Applied;
+            }
             case 'lyrics':
                 let lyricsLine = 0;
                 let lyricsText = '';

packages/alphatab/src/model/Beat.ts

@@ -424,6 +424,18 @@ export class Beat {
      */
     public deadSlapped: boolean = false;
 
+    /**
+     * Gets or sets the chromatic tone value (0–11) of the pitch at which this rest should be displayed.
+     * A value of -1 means use the default position formula.
+     */
+    public restDisplayTone: number = -1;
+
+    /**
+     * Gets or sets the octave at which this rest should be displayed.
+     * Only relevant when {@link restDisplayTone} is set. -1 means use the default position formula.
+     */
+    public restDisplayOctave: number = -1;
+
     /**
      * Gets or sets the brush type applied to the notes of this beat.
      */

packages/alphatab/src/rendering/glyphs/ScoreBeatGlyph.ts

@@ -1,5 +1,6 @@
 import { Logger } from '@coderline/alphatab/Logger';
 import { AccentuationType } from '@coderline/alphatab/model/AccentuationType';
+import { AccidentalHelper } from '@coderline/alphatab/rendering/utils/AccidentalHelper';
 import { BeatSubElement } from '@coderline/alphatab/model/Beat';
 import { Duration } from '@coderline/alphatab/model/Duration';
 import { GraceType } from '@coderline/alphatab/model/GraceType';
@@ -301,17 +302,20 @@ export class ScoreBeatGlyph extends BeatOnNoteGlyphBase {
 
     private _createRestGlyphs() {
         const sr = this.renderer as ScoreBarRenderer;
+        const beat = this.container.beat;
+        const lineCount = this.renderer.bar.staff.standardNotationLineCount;
 
-        let steps = Math.ceil((this.renderer.bar.staff.standardNotationLineCount - 1) / 2) * 2;
+        let steps: number;
+        if (beat.restDisplayTone !== -1 && beat.restDisplayOctave !== -1) {
+            steps = AccidentalHelper.calculateRestDisplaySteps(sr.bar, beat.restDisplayTone, beat.restDisplayOctave);
+        } else {
+            steps = Math.ceil((lineCount - 1) / 2) * 2;
+        }
 
         // this positioning is quite strange, for most staff line counts
         // the whole/rest are aligned as half below the whole rest.
         // but for staff line count 1 and 3 they are aligned centered on the same line.
-        if (
-            this.container.beat.duration === Duration.Whole &&
-            this.renderer.bar.staff.standardNotationLineCount !== 1 &&
-            this.renderer.bar.staff.standardNotationLineCount !== 3
-        ) {
+        if (beat.duration === Duration.Whole && lineCount !== 1 && lineCount !== 3) {
             steps -= 2;
         }
 

packages/alphatab/src/rendering/utils/AccidentalHelper.ts

@@ -5,6 +5,7 @@ import type { Clef } from '@coderline/alphatab/model/Clef';
 import { ModelUtils, type ResolvedSpelling } from '@coderline/alphatab/model/ModelUtils';
 import type { Note } from '@coderline/alphatab/model/Note';
 import { NoteAccidentalMode } from '@coderline/alphatab/model/NoteAccidentalMode';
+import { Ottavia } from '@coderline/alphatab/model/Ottavia';
 import { PercussionMapper } from '@coderline/alphatab/model/PercussionMapper';
 import type { LineBarRenderer } from '@coderline/alphatab/rendering/LineBarRenderer';
 import type { ScoreBarRenderer } from '@coderline/alphatab/rendering/ScoreBarRenderer';
@@ -267,6 +268,28 @@ export class AccidentalHelper {
         return steps;
     }
 
+    public static calculateRestDisplaySteps(bar: Bar, tone: number, octave: number): number {
+
+        let noteValue = (octave + 1) * 12 + tone;
+        switch (bar.clefOttava) {
+            case Ottavia._15ma:
+                noteValue -= 24;
+                break;
+            case Ottavia._8va:
+                noteValue -= 12;
+                break;
+            case Ottavia._8vb:
+                noteValue += 12;
+                break;
+            case Ottavia._15mb:
+                noteValue += 24;
+                break;
+        }
+
+        const spelling = ModelUtils.resolveSpelling(bar.keySignature, noteValue, NoteAccidentalMode.Default);
+        return AccidentalHelper.calculateNoteSteps(bar.clef, spelling) + 0.5;
+    }
+
     public getNoteSteps(n: Note): number {
         return this._appliedScoreSteps.get(n.id)!;
     }

packages/alphatab/test/visualTests/features/RestPosition.test.ts

@@ -0,0 +1,197 @@
+import { describe, it } from 'vitest';
+import { VisualTestHelper } from 'test/visualTests/VisualTestHelper';
+
+interface PitchPosition {
+    pitch: string;
+    label: string;
+}
+
+interface ClefData {
+    clef: string;
+    tex: string;
+    filler: string;
+    primaryFiller: string;
+    secondaryFiller: string;
+    multiVoicePrimary: PitchPosition;
+    multiVoiceSecondary: PitchPosition;
+    positions: PitchPosition[];
+}
+
+// Staff positions from bottom to top for each clef
+const clefs: ClefData[] = [
+    {
+        clef: 'treble',
+        tex: '',
+        filler: 'b4',
+        positions: [
+            { pitch: 'E4', label: 'Line 1' },
+            { pitch: 'F4', label: 'Space 1' },
+            { pitch: 'G4', label: 'Line 2' },
+            { pitch: 'A4', label: 'Space 2' },
+            { pitch: 'B4', label: 'Line 3' },
+            { pitch: 'C5', label: 'Space 3' },
+            { pitch: 'D5', label: 'Line 4' },
+            { pitch: 'E5', label: 'Space 4' },
+            { pitch: 'F5', label: 'Line 5' },
+            { pitch: 'G5', label: 'Space 5' }
+        ],
+        primaryFiller: 'e5',
+        secondaryFiller: 'e4',
+        multiVoicePrimary: { pitch: 'C5', label: 'Space 3' },
+        multiVoiceSecondary: { pitch: 'E4', label: 'Line 1' }
+    },
+    {
+        clef: 'bass',
+        tex: '\\clef bass',
+        filler: 'd3',
+        positions: [
+            { pitch: 'G2', label: 'Line 1' },
+            { pitch: 'A2', label: 'Space 1' },
+            { pitch: 'B2', label: 'Line 2' },
+            { pitch: 'C3', label: 'Space 2' },
+            { pitch: 'D3', label: 'Line 3' },
+            { pitch: 'E3', label: 'Space 3' },
+            { pitch: 'F3', label: 'Line 4' },
+            { pitch: 'G3', label: 'Space 4' },
+            { pitch: 'A3', label: 'Line 5' },
+            { pitch: 'B3', label: 'Space 5' }
+        ],
+        primaryFiller: 'a3',
+        secondaryFiller: 'g2',
+        multiVoicePrimary: { pitch: 'E3', label: 'Space 3' },
+        multiVoiceSecondary: { pitch: 'G2', label: 'Line 1' }
+    },
+    {
+        clef: 'alto',
+        tex: '\\clef alto',
+        filler: 'c4',
+        positions: [
+            { pitch: 'F3', label: 'Line 1' },
+            { pitch: 'G3', label: 'Space 1' },
+            { pitch: 'A3', label: 'Line 2' },
+            { pitch: 'B3', label: 'Space 2' },
+            { pitch: 'C4', label: 'Line 3' },
+            { pitch: 'D4', label: 'Space 3' },
+            { pitch: 'E4', label: 'Line 4' },
+            { pitch: 'F4', label: 'Space 4' },
+            { pitch: 'G4', label: 'Line 5' },
+            { pitch: 'A4', label: 'Space 5' }
+        ],
+        primaryFiller: 'g4',
+        secondaryFiller: 'f3',
+        multiVoicePrimary: { pitch: 'D4', label: 'Space 3' },
+        multiVoiceSecondary: { pitch: 'F3', label: 'Line 1' }
+    },
+    {
+        clef: 'tenor',
+        tex: '\\clef tenor',
+        filler: 'a3',
+        positions: [
+            { pitch: 'D3', label: 'Line 1' },
+            { pitch: 'E3', label: 'Space 1' },
+            { pitch: 'F3', label: 'Line 2' },
+            { pitch: 'G3', label: 'Space 2' },
+            { pitch: 'A3', label: 'Line 3' },
+            { pitch: 'B3', label: 'Space 3' },
+            { pitch: 'C4', label: 'Line 4' },
+            { pitch: 'D4', label: 'Space 4' },
+            { pitch: 'E4', label: 'Line 5' },
+            { pitch: 'F4', label: 'Space 5' }
+        ],
+        primaryFiller: 'e4',
+        secondaryFiller: 'd3',
+        multiVoicePrimary: { pitch: 'B3', label: 'Space 3' },
+        multiVoiceSecondary: { pitch: 'D3', label: 'Line 1' }
+    }
+];
+
+function restBeat(pitch: string, label: string, duration: string, showLabel: boolean = true): string {
+    if (showLabel) {
+        return `r.${duration}{restDisplayPitch ${pitch} txt "${label}"}`;
+    }
+    return `r.${duration}{restDisplayPitch ${pitch}}`;
+}
+
+function clefPrimaryDurations(tex: string, filler: string, pitch: string, label: string): string {
+    const prefix = tex ? `${tex} ` : '';
+    return `${prefix}${restBeat(pitch, label, '1')} | ${restBeat(pitch, label, '2')} ${filler}.2 | ${restBeat(pitch, label, '4')} ${filler}.4 *3 | ${restBeat(pitch, label, '8')} ${filler}.8 *7 | ${restBeat(pitch, label, '16')} ${filler}.16 *15 | ${restBeat(pitch, label, '32')} ${filler}.32 *31`;
+}
+
+function voicePrimaryDurations(filler: string, pitch: string, label: string): string {
+    return `${restBeat(pitch, label, '1')} | ${restBeat(pitch, label, '2')} ${filler}.2 | ${restBeat(pitch, label, '4')} ${filler}.4 *3 | ${restBeat(pitch, label, '8')} ${filler}.8 *7 | ${restBeat(pitch, label, '16')} ${filler}.16 *15 | ${restBeat(pitch, label, '32')} ${filler}.32 *31`;
+}
+
+function voiceSecondaryDurations(filler: string, pitch: string, label: string): string {
+    return `${filler}.1 | ${filler}.2 ${restBeat(pitch, label, '2')} | ${filler}.4 *3 ${restBeat(pitch, label, '4')} | ${filler}.8 *7 ${restBeat(pitch, label, '8')} | ${filler}.16 *15 ${restBeat(pitch, label, '16')} | ${filler}.32 *31 ${restBeat(pitch, label, '32')}`;
+}
+
+function voiceDefaultPrimary(filler: string): string {
+    return `r.1 | r.2 ${filler}.2 | r.4 ${filler}.4 *3 | r.8 ${filler}.8 *7 | r.16 ${filler}.16 *15 | r.32 ${filler}.32 *31`;
+}
+
+function voiceDefaultSecondary(filler: string): string {
+    return `${filler}.1 | ${filler}.2 r.2 | ${filler}.4 *3 r.4 | ${filler}.8 *7 r.8 | ${filler}.16 *15 r.16 | ${filler}.32 *31 r.32`;
+}
+
+describe('RestPositionTests', () => {
+    it('rest-position-default', async () => {
+        await VisualTestHelper.runVisualTestTex(
+            `r.1 | r.2 e5.2 | r.4 e5.4 *3 | r.8 e5.8 *7 | r.16 e5.16 *15 | r.32 e5.32 *31`,
+            'test-data/visual-tests/rest-position/rest-position-default.png'
+        );
+    });
+
+    for (const clefData of clefs) {
+        describe(`rest-position-${clefData.clef}`, () => {
+            const prefix = clefData.tex ? `${clefData.tex} ` : '';
+
+            for (const pos of clefData.positions) {
+                it(`position-${pos.pitch} - ${pos.label}`, async () => {
+                    await VisualTestHelper.runVisualTestTex(
+                        clefPrimaryDurations(clefData.tex, clefData.filler, pos.pitch, pos.label),
+                        `test-data/visual-tests/rest-position/${clefData.clef}/rest-position-pitch-${pos.pitch}-${pos.label.toLowerCase().replace(' ', '-')}.png`
+                    );
+                });
+            }
+
+            it('multi-voice-default', async () => {
+                await VisualTestHelper.runVisualTestTex(
+                    `${prefix}\\voice ${voiceDefaultPrimary(clefData.primaryFiller)} \\voice ${voiceDefaultSecondary(clefData.secondaryFiller)}`,
+                    `test-data/visual-tests/rest-position/${clefData.clef}/rest-position-multi-voice-default.png`
+                );
+            });
+
+            it('multi-voice-both-set', async () => {
+                await VisualTestHelper.runVisualTestTex(
+                    `${prefix}\\voice ${voicePrimaryDurations(clefData.primaryFiller, clefData.multiVoicePrimary.pitch, clefData.multiVoicePrimary.label)} \\voice ${voiceSecondaryDurations(clefData.secondaryFiller, clefData.multiVoiceSecondary.pitch, clefData.multiVoiceSecondary.label)}`,
+                    `test-data/visual-tests/rest-position/${clefData.clef}/rest-position-multi-voice-both-set.png`
+                );
+            });
+
+            it('multi-voice-main-only', async () => {
+                await VisualTestHelper.runVisualTestTex(
+                    `${prefix}\\voice ${voicePrimaryDurations(clefData.primaryFiller, clefData.multiVoicePrimary.pitch, clefData.multiVoicePrimary.label)} \\voice ${voiceDefaultSecondary(clefData.secondaryFiller)}`,
+                    `test-data/visual-tests/rest-position/${clefData.clef}/rest-position-multi-voice-main-only-${clefData.multiVoicePrimary.pitch}-${clefData.multiVoicePrimary.label.toLowerCase().replace(' ', '-')}.png`
+                );
+            });
+
+            it('multi-voice-secondary-only', async () => {
+                await VisualTestHelper.runVisualTestTex(
+                    `${prefix}\\voice ${voiceDefaultPrimary(clefData.primaryFiller)} \\voice ${voiceSecondaryDurations(clefData.secondaryFiller, clefData.multiVoiceSecondary.pitch, clefData.multiVoiceSecondary.label)}`,
+                    `test-data/visual-tests/rest-position/${clefData.clef}/rest-position-multi-voice-secondary-only-${clefData.multiVoiceSecondary.pitch}-${clefData.multiVoiceSecondary.label.toLowerCase().replace(' ', '-')}.png`
+                );
+            });
+
+            describe('staff-lines', () => {
+                for (const lineCount of [1, 2, 3, 4, 5]) {
+                    it(`linecount-${lineCount}`, async () => {
+                        await VisualTestHelper.runVisualTestTex(
+                            `${prefix}\\staff { score ${lineCount} } ${restBeat(clefData.multiVoiceSecondary.pitch, clefData.multiVoiceSecondary.label, '1', false)} | ${restBeat(clefData.multiVoiceSecondary.pitch, clefData.multiVoiceSecondary.label, '2', false)} ${clefData.secondaryFiller}.2 | ${restBeat(clefData.multiVoiceSecondary.pitch, clefData.multiVoiceSecondary.label, '4', false)} ${clefData.secondaryFiller}.4 *3`,
+                            `test-data/visual-tests/rest-position/${clefData.clef}/rest-position-staff-lines-${lineCount}-${clefData.multiVoiceSecondary.pitch}.png`
+                        );
+                    });
+                }
+            });
+        });
+    }
+});