[ << Musical notation ][Top][Contents][Index][ Specialist notation >> ]
[ < Font features ][ Up : Fonts ][]

Single entry fonts

Almost all outline fonts installed on the operating system and recognized by FontConfig may be used in a score, with the exception of bitmap fonts (which are not supported by design) and OpenType Variation Fonts (which are not supported yet).

LilyPond calls function pango_font_description_from_string from the Pango library to access fonts; it uses the following syntax form for font names.1 

[family-list] [style-options]

where family-list is a comma-separated list of families optionally terminated by a comma, and style-options a whitespace-separated list of words where each word describes one of style, variant, weight, stretch, or gravity.

The following words are understood as styles: Normal (the default), Roman, Oblique, Italic.

The following words are understood as variants: Small-Caps. Default is no variant.

The following words are understood as weights: Thin, Ultra-Light, Extra-Light, Light, Semi-Light, Demi-Light, Book, Regular (the default), Medium, Semi-Bold, Demi-Bold, Bold, Ultra-Bold, Extra-Bold, Heavy, Black, Ultra-Black, Extra-Black.

The following words are understood as stretch values: Ultra-Condensed, Extra-Condensed, Condensed, Semi-Condensed, Semi-Expanded, Expanded, Extra-Expanded, Ultra-Expanded. Default is no stretch.

The following words are understood as gravity values: Not-Rotated, South, Upside-Down, North, Rotated-Left, East, Rotated-Right, West. Default is no gravity.

Assuming the syntax is correct, setting a font name never fails. If none of the font families are known (or no font family is given), FontConfig returns a default font depending on the operating system. If none of the style options are known (or no style option is given), default values are used.

In the following example, the font for the time signature is set to ‘Bitstream Charter’. Since no style option is given, FontConfig uses default values as specified above. For the markup string, the list of font families is set to ‘Bitstream Vera Sans’ and ‘sans-serif’, which tells FontConfig to try ‘Bitstream Vera Sans’ first; if it is not available, it tries the generic font family ‘sans-serif’ as described in Font families. The style for the markup is set to ‘Oblique Bold’, which makes FontConfig try to find a font that is both oblique and bold. If that fails, it tries to find an oblique or bold font. If that fails again, it tries to match a font with default style options.

Note that FontConfig also checks whether the requested glyph is actually present in the font. In case it is missing, another font gets tried (following the above algorithm) until the glyph is eventually found. Only if FontConfig fails to find any font with the appropriate glyph a symbol for a missing glyph is shown (which is normally a rectangular box or simply some whitespace). 

\override Staff.TimeSignature.font-name = "Bitstream Charter"
\override Staff.TimeSignature.font-size = #2
\time 3/4

a'1_\markup {
  \override #'(font-name .
               "Bitstream Vera Sans, sans-serif, Oblique Bold")
    { Vera Oblique Bold }
}

[image of music]

Note: If any of the above style options is part of the font (family) name you must use a trailing comma after the name even if you do not select a style option. A typical example is ‘Times New Roman’: If specified as "Times New Roman", FontConfig searches for a font ‘Times New’ in roman style. Only if you say "Times New Roman," this font is really accessed.

Running lilypond on the command line with the following option displays a list of all available fonts on the operating system: 

lilypond -dshow-available-fonts

See also

Notation Reference: Finding fonts, Font families, Entire document fonts.

Snippets: Text.

Footnotes

[1] The data is taken from the Pango reference for version 1.46.1; the syntax supported by LilyPond is actually a subset of what Pango provides.

[ << Musical notation ][Top][Contents][Index][ Specialist notation >> ]
[ < Font features ][ Up : Fonts ][]

<< Back to Documentation Index

LilyPond — Notation Reference v2.25.4 (development-branch).