feat(rendering): add per-beat rest display position via restDisplayPitch tag

Adds Beat.restDisplayTone (Tone enum) and Beat.restDisplayOctave to allow
specifying the vertical position of a rest on the staff on a per-beat basis.
The AlphaTex restdisplaypitch tag (e.g. r.4{restdisplaypitch E4}) sets these
values. AccidentalHelper.calculateRestDisplaySteps converts the pitch to
rendering steps, aligned to match the legacy RestPosition enum spacing (+0.5).

Includes 77 visual tests covering treble, bass, alto and tenor clefs across
all staff positions, durations, multi-voice scenarios, and variable line counts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: roscopeeco

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

@@ -16,6 +16,7 @@ import { Ottavia } from "@coderline/alphatab/model/Ottavia";
 import { Duration } from "@coderline/alphatab/model/Duration";
 import { Automation } from "@coderline/alphatab/model/Automation";
 import { FadeType } from "@coderline/alphatab/model/FadeType";
+import { Tone } from "@coderline/alphatab/model/Tone";
 import { BrushType } from "@coderline/alphatab/model/BrushType";
 import { WhammyType } from "@coderline/alphatab/model/WhammyType";
 import { BendPoint } from "@coderline/alphatab/model/BendPoint";
@@ -64,6 +65,8 @@ export class BeatSerializer {
         o.set("text", obj.text);
         o.set("slashed", obj.slashed);
         o.set("deadslapped", obj.deadSlapped);
+        o.set("restdisplaytone", obj.restDisplayTone as number | null);
+        o.set("restdisplayoctave", obj.restDisplayOctave);
         o.set("brushtype", obj.brushType as number);
         o.set("brushduration", obj.brushDuration);
         o.set("tupletdenominator", obj.tupletDenominator);
@@ -165,6 +168,12 @@ export class BeatSerializer {
             case "deadslapped":
                 obj.deadSlapped = v! as boolean;
                 return true;
+            case "restdisplaytone":
+                obj.restDisplayTone = JsonHelper.parseEnum<Tone>(v, Tone) ?? null;
+                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

@@ -70,6 +70,7 @@ import { NoteAccidentalMode } from '@coderline/alphatab/model/NoteAccidentalMode
 import { NoteOrnament } from '@coderline/alphatab/model/NoteOrnament';
 import { Ottavia } from '@coderline/alphatab/model/Ottavia';
 import { PercussionMapper } from '@coderline/alphatab/model/PercussionMapper';
+import { Tone } from '@coderline/alphatab/model/Tone';
 import { PickStroke } from '@coderline/alphatab/model/PickStroke';
 import { BarNumberDisplay, type RenderStylesheet } from '@coderline/alphatab/model/RenderStylesheet';
 import { HeaderFooterStyle, Score, ScoreStyle, ScoreSubElement } from '@coderline/alphatab/model/Score';
@@ -1616,6 +1617,25 @@ export class AlphaTex1LanguageHandler implements IAlphaTexLanguageImportHandler
             case 'txt':
                 beat.text = (p.arguments!.arguments[0] as AlphaTexTextNode).text;
                 return ApplyNodeResult.Applied;
+            case 'restdisplaypitch': {
+                const pitchText = (p.arguments!.arguments[0] as AlphaTexTextNode).text.toUpperCase();
+                const toneChar = pitchText[0] as keyof typeof Tone;
+                const octave = parseInt(pitchText.slice(1));
+                if (toneChar in Tone && !isNaN(octave)) {
+                    beat.restDisplayTone = Tone[toneChar];
+                    beat.restDisplayOctave = octave;
+                } else {
+                    importer.addSemanticDiagnostic({
+                        code: AlphaTexDiagnosticCode.AT212,
+                        message: `Invalid pitch value '${pitchText}', 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

@@ -12,6 +12,7 @@ import type { Fermata } from '@coderline/alphatab/model/Fermata';
 import { GraceType } from '@coderline/alphatab/model/GraceType';
 import { Note } from '@coderline/alphatab/model/Note';
 import { Ottavia } from '@coderline/alphatab/model/Ottavia';
+import { Tone } from '@coderline/alphatab/model/Tone';
 import { PickStroke } from '@coderline/alphatab/model/PickStroke';
 import type { Slur } from '@coderline/alphatab/model/Slur';
 import { TupletGroup } from '@coderline/alphatab/model/TupletGroup';
@@ -424,6 +425,18 @@ export class Beat {
      */
     public deadSlapped: boolean = false;
 
+    /**
+     * Gets or sets the tone of the pitch at which this rest should be displayed.
+     * Use values from the {@link Tone} enum. Null means use the default position formula.
+     */
+    public restDisplayTone: Tone | null = null;
+
+    /**
+     * 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/model/Tone.ts

@@ -0,0 +1,14 @@
+/**
+ * Represents the diatonic tone (note name) within an octave.
+ * Used as the value for {@link Beat.restDisplayTone} to specify where a rest should be displayed on the staff.
+ * @public
+ */
+export enum Tone {
+    C = 0,
+    D = 2,
+    E = 4,
+    F = 5,
+    G = 7,
+    A = 9,
+    B = 11
+}

packages/alphatab/src/model/_barrel.ts

@@ -42,6 +42,7 @@ export { Note, NoteSubElement, NoteStyle } from '@coderline/alphatab/model/Note'
 export { NoteAccidentalMode } from '@coderline/alphatab/model/NoteAccidentalMode';
 export { NoteOrnament } from '@coderline/alphatab/model/NoteOrnament';
 export { Ottavia } from '@coderline/alphatab/model/Ottavia';
+export { Tone } from '@coderline/alphatab/model/Tone';
 export { PickStroke } from '@coderline/alphatab/model/PickStroke';
 export { PlaybackInformation } from '@coderline/alphatab/model/PlaybackInformation';
 export { Rasgueado } from '@coderline/alphatab/model/Rasgueado';

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 !== null && 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)!;
     }