Skip to main content

Tuning display

Show the string tuning at the top of the score, hide it entirely, or move it beside each tab-staff line. Three stylesheet fields โ€” one score-wide toggle, one per-track override, and a placement enum โ€” cover every combination. Use them to hide the tuning on repeated systems where the header wastes space, or to show per-staff tuning in a multi-guitar chart where each track sits in a different tuning.

  • Score (block above)
  • Staff (next to lines)

The knobsโ€‹

Three fields on score.stylesheet control tuning display:

  • globalDisplayTuning โ€” a boolean, true by default. When false, no tuning label appears anywhere in the render.
  • perTrackDisplayTuning โ€” a Map<number, boolean> keyed by track index. Add an entry to override the global flag for that specific track. Leave the map null (default) to apply the global flag uniformly.
  • tuningDisplayMode โ€” a TuningDisplayMode enum controlling where the tuning is placed:
    • Score โ€” the tuning block sits above the first system, alongside title and artist info (default).
    • Staff โ€” each open-string pitch is written next to its tab-staff line, replacing the block header. See Tuning on the staff lines.

Staff mode reads best when a score contains multiple string instruments with different tunings; each label appears next to its own staff instead of one combined block. Score mode is cleaner for single-instrument charts.

Tuning on the staff lines (new in 1.9)โ€‹

With TuningDisplayMode.Staff, alphaTab writes the note name of each open string at the left end of its tab line on the first system. This matches the "tuning before staff" option in Guitar Pro. Every tab staff shows its own tuning, and tracks hidden through perTrackDisplayTuning stay hidden.

00:00
00:00
\tuningDisplayMode staff
\track "Guitar"
\staff { tabs }
\tuning (E4 B3 G3 D3 A2 D2)
:8 0.6 2.4 0.3 2.2 0.1 2.2 0.3 2.4 | :8 0.6 2.4 0.3 2.2 0.1 2.2 0.3 2.4
\track "Bass"
\staff { tabs }
\tuning (G2 D2 A1 D1)
:4 0.4 0.4 0.4 0.4 | 0.4 0.4 0.4 0.4
  • display.inlineTuningPaddingRight sets the gap between the labels and the start of the tab staff. The default is 5.
  • In alphaTex, \tuningDisplayMode takes score or staff. The alphaTex exporter writes the tag when the mode is not score.
  • Guitar Pro 7 and 8 files store the mode in their stylesheet. alphaTab reads it on import and writes it back in the Guitar Pro 7 exporter.

Sharp and flat tunings (new in 1.10)โ€‹

alphaTab labels every string with its written pitch. A string tuned to the same pitch as F#3 or Gb3 keeps the spelling of the source file, and the score tuning and the staff tuning show it with the accidental characters โ™ฏ and โ™ญ of the tuning font.

\track "Guitar"
\staff { tabs }
\tuning (D#4 A#3 F#3 C#3 G#2 D#2)
:4 0.6 2.5 2.4 0.3 | 0.2 2.3 0.1 r
\track "Baritone"
\staff { tabs }
\tuning (Bb3 F3 Db3 Ab2 Eb2 Bb1)
:4 0.6 2.5 2.4 0.3 | 0.2 2.3 0.1 r
  • alphaTex keeps the tuning as written in \tuning and writes it back on export.
  • MusicXML files define the spelling with tuning-step and tuning-alter.
  • Guitar Pro files mark a tuning written with flats, all other tunings are written with sharps. The Guitar Pro 7 exporter writes the choice back.
  • Formats without a spelling, like Guitar Pro 3-5, and tunings set as MIDI values are written with flats, as in earlier versions.

In code, Tuning.pitches holds a SpelledPitch for every string, starting with the highest string. Tuning.tunings gives the MIDI values of the same strings; setting it spells the strings with flats. Assign a new array to change the tuning:

import * as alphaTab from '@coderline/alphatab';

const container = getAlphaTabContainer();
const api = new alphaTab.AlphaTabApi(container, {
core: { file: '/scores/song.gp' },
});

api.scoreLoaded.on((score) => {
const tuning = score.tracks[0].staves[0].stringTuning;
// D# A# F# C# G# D#, written with sharps
tuning.pitches = [
new alphaTab.model.SpelledPitch(1, 1, 4),
new alphaTab.model.SpelledPitch(5, 1, 3),
new alphaTab.model.SpelledPitch(3, 1, 3),
new alphaTab.model.SpelledPitch(0, 1, 3),
new alphaTab.model.SpelledPitch(4, 1, 2),
new alphaTab.model.SpelledPitch(1, 1, 2),
];
console.log(tuning.pitches[0].toString(), tuning.tunings[0]); // D#4 63
api.render();
});

Show it in codeโ€‹

import * as alphaTab from '@coderline/alphatab';

const container = getAlphaTabContainer();
const api = new alphaTab.AlphaTabApi(container, {
core: { file: '/scores/song.gp' },
display: { inlineTuningPaddingRight: 8 },
});

api.scoreLoaded.on((score) => {
const s = score.stylesheet;
s.globalDisplayTuning = true;
s.tuningDisplayMode = alphaTab.model.TuningDisplayMode.Staff;

// Hide tuning on a specific track (e.g. a piano track that has none):
s.perTrackDisplayTuning = new Map();
for (const track of score.tracks) {
if (track.staves[0].tuning.length === 0) {
s.perTrackDisplayTuning.set(track.index, false);
}
}

api.render();
});

getAlphaTabContainer() is a placeholder for the platform-specific step of obtaining the render target โ€” a <div> on Web, an AlphaTab control on .NET, or an AlphaTabView on Android. Every other line runs unchanged on all three runtimes.

Where to look nextโ€‹