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)

Hide tuning globally

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.

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 GuitarTuning element globally through notation.elements.
• globalDisplayTuning, perTrackDisplayTuning, and tuningDisplayMode on the RenderStylesheet reference.
• TuningDisplayMode — the enum reference.
• display.inlineTuningPaddingRight and \tuningDisplayMode — the padding setting and the alphaTex tag.
• scoreLoaded and render — the API surface used above.