Skip to main content

Using a custom music font

alphaTab renders every notehead, clef, accidental, dynamic, and ornament through a single SMuFL-compliant font. Bravura is the default; swap it out to match a house style โ€” Petaluma for a handwritten look on lead sheets and jam charts, Leland for parity with MuseScore's default engraving, or a purpose-built house font shared across a publishing catalogue.

The render above uses Petaluma, a handwritten-style SMuFL font, in place of Bravura โ€” both the font file and the metadata sidecar are loaded at runtime.

What alphaTab draws from the fontโ€‹

alphaTab reaches into the SMuFL Standard glyph range for every graphical element that is not a text label. That includes:

  • Notation basics โ€” noteheads (round, X, slash, diamond, triangle), stems, flags, rests, augmentation dots, ties, and beams.
  • Signatures โ€” clefs (G, F, C, percussion, tab), key signature accidentals, and time signature digits.
  • Effects โ€” ornaments (trill, mordent, turn), articulations (accent, staccato, tenuto), fermatas, harmonics, palm mute, let ring.
  • Dynamics and directions โ€” dynamic letters (ppp through fff), crescendo hairpins, D.C. / D.S. / segno / coda symbols.
  • Guitar-specific glyphs โ€” bend arrows, whammy hooks, slide indicators, string tuning numerals.

A font that omits any of these ranges renders those elements as the font's placeholder or as blanks. Bravura, Petaluma, and Leland cover the full range alphaTab uses. Other SMuFL fonts vary โ€” inspect the font's glyph inventory before committing.

The two halves of a SMuFL fontโ€‹

Every SMuFL font ships as two files that must stay in sync:

  • The font file โ€” an .otf, .woff, or .woff2 binary. alphaTab loads it via core.smuflFontSources, a Map<FontFileFormat, string> of URLs. Multiple formats can be listed at once; the browser picks the first it supports.
  • The metadata.json sidecar โ€” a JSON file published alongside the font describing engraving metrics: stem thicknesses, staff-line spacing, anchor points on each notehead. Fetch it and hand it to display.resources.engravingSettings.fillFromSmufl() so alphaTab spaces glyphs correctly.

Skip the metadata and the font renders with Bravura's spacing rules applied to different-shaped glyphs โ€” the result looks subtly wrong at every scale. Skip the font file and the metadata has nothing to describe.

Show it in codeโ€‹

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

const settings = new alphaTab.Settings();
settings.core.smuflFontSources = new Map([
  [alphaTab.FontFileFormat.Woff2, '/fonts/Petaluma.woff2'],
  [alphaTab.FontFileFormat.OpenType, '/fonts/Petaluma.otf'],
]);

const metadata = await fetch('/fonts/petaluma_metadata.json').then((r) => r.json());
settings.display.resources.engravingSettings.fillFromSmufl(metadata);

const container = getAlphaTabContainer();
const api = new alphaTab.AlphaTabApi(container, settings);

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.

Limitationsโ€‹

  • No live font swap. Reassigning smuflFontSources on a running instance does not re-render with the new font. Destroy the AlphaTabApi and create a fresh one to switch fonts at runtime.
  • Incomplete fonts. Few SMuFL fonts cover the full glyph range alphaTab uses. alphaTab has no per-glyph fallback โ€” missing glyphs render as gaps or as the font's own placeholder. Bravura, Petaluma, and Leland are the safest choices.

Building or picking a compatible fontโ€‹

If you want to author a new SMuFL font instead of adopting an existing one:

  • Start from the SMuFL specification โ€” glyph codepoints are stable across every compliant font.
  • Publish a metadata.json following the Bravura reference. alphaTab reads engravingDefaults, glyph anchor points (stemUpSE, stemDownNW, cutOutNW, etc.), and bounding boxes.
  • Ship at least .woff2 and .otf. On .NET and Android alphaTab uses the OpenType variant.
  • Cover the full glyph range alphaTab draws (listed above). Missing glyphs do not fall back โ€” they render as gaps.

Licensingโ€‹

The default Bravura font is licensed under SIL Open Font License 1.1 and ships with alphaTab. Every SMuFL font you swap in carries its own license. Petaluma is SIL OFL 1.1; Leland is SIL OFL 1.1. Check the license of any font before redistributing it inside a commercial product โ€” some SMuFL-compliant fonts are proprietary and require paid distribution rights.

Where to look nextโ€‹