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,trueby default. Whenfalse, no tuning label appears anywhere in the render.perTrackDisplayTuningโ aMap<number, boolean>keyed by track index. Add an entry to override the global flag for that specific track. Leave the mapnull(default) to apply the global flag uniformly.tuningDisplayModeโ aTuningDisplayModeenum 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.
\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.inlineTuningPaddingRightsets the gap between the labels and the start of the tab staff. The default is5.- In alphaTex,
\tuningDisplayModetakesscoreorstaff. The alphaTex exporter writes the tag when the mode is notscore. - 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
\tuningand writes it back on export. - MusicXML files define the spelling with
tuning-stepandtuning-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โ
- Guitar tablature โ the tab staff that this tuning label describes.
- Special tracks โ how alternate tunings render across mixed instrument sets.
- Toggling notation elements off โ hide the
GuitarTuningelement globally throughnotation.elements. globalDisplayTuning,perTrackDisplayTuning, andtuningDisplayModeon theRenderStylesheetreference.TuningDisplayModeโ the enum reference.TuningandSpelledPitchโ the tuning values and their written spelling.display.inlineTuningPaddingRightand\tuningDisplayModeโ the padding setting and the alphaTex tag.scoreLoadedandrenderโ the API surface used above.