[ << Musical notation ][Top][Contents][Index][ Specialist notation >> ]
[ < Music notation inside markup ][ Up : Text ][]

1.8.3 Fonts

Fonts in LilyPond are handled by several libraries; two of them are of relevance to the user: FontConfig is used to detect available fonts, and selected fonts are then rendered by Pango to display text strings.

This section shows how to access fonts in LilyPond, and how to change them in scores.

Finding fonts  
Font families  
Font features  
Single entry fonts  
Entire document fonts  
Music fonts  
[ << Musical notation ][Top][Contents][Index][ Specialist notation >> ]
[ < Fonts ][ Up : Fonts ][]

Finding fonts

In addition to any font already installed on the operating system, more fonts may be added to the ones detected by FontConfig (and thus available in LilyPond scores) by the following commands: 

#(ly:font-config-add-font "path/to/font-file")
#(ly:font-config-add-directory "path/to/directory/")

Both commands accept either absolute or relative paths, which makes it possible to compile a score on any system by simply distributing the relevant font files together with the LilyPond input files.

To verify that the desired fonts are found by FontConfig, use the command #(ly:font-config-display-fonts), which prints the complete list of available fonts to the console log. It also shows the actual font names to be used with LilyPond; these may differ from the file names themselves.

See Single entry fonts and Entire document fonts how to access fonts in general.

[ << Musical notation ][Top][Contents][Index][ Specialist notation >> ]
[ < Finding fonts ][ Up : Fonts ][]

Font families

Three generic aliases for text font families1 are available: ‘roman’ (serif), ‘sans’, and ‘typewriter’. Depending on the backend, these families get mapped to different font family aliases.

For the svg backend:

generic familySVG font family
romanserif
sanssans-serif
typewritermonospace

‘serif’, ‘sans-serif’, and ‘monospace’ are ‘generic-family’ in SVG and CSS specifications.

For other backends:

generic familydefault font family aliasfont families contained in alias
romanLilyPond SerifC059, Century SchoolBook URW, Century Schoolbook L, TeX Gyre Schola, DejaVu Serif, …, serif
sansLilyPond Sans SerifNimbus Sans, Nimbus Sans L, TeX Gyre Heros, DejaVu Sans, …, sans-serif
typewriterLilyPond MonospaceNimbus Mono PS, Nimbus Mono, Nimbus Mono L, TeX Gyre Cursor, DejaVu Sans Mono, …, monospace

If a character does not exist in the appropriate font of the first listed family, the appropriate font of the next listed family gets used instead for that character.

Note that the URW font families distributed with LilyPond (‘C059’, ‘Nimbus Sans’, and ‘Nimbus Mono PS’) have a peculiarity: By default, in addition to the standard ligatures like ‘fl’ or ‘ffi’, they substitute the string ‘Nr.’ with the Numero Sign (U+2116) if the ‘latn’ script is selected. To circumvent this locally, insert a zero-width non-joiner character (ZWNJ, U+200C) between the ‘N’ and ‘r’ characters. To circumvent this globally, use the following code to make LilyPond always insert a ZWNJ character. 

\paper {
  #(add-text-replacements!
      `(("Nr." . ,(format #f "N~ar." (ly:wide-char->utf-8 #x200C)))))
}

‘LilyPond Serif’, ‘LilyPond Sans Serif’, and ‘LilyPond Monospace’ are font family aliases defined in the additional FontConfig configuration file ‘00-lilypond-fonts.conf’, which can be usually found in directory ‘/usr/local/share/lilypond/2.24.4/fonts’, and which is used exclusively by LilyPond.

Each font family may include different shapes and series. The following example demonstrates that, including code to also change the size. The value supplied to font-size is taken relative to the default font size. 

\override Score.TextMark.font-family = #'typewriter
\textMark "Ouverture"
\override Voice.TextScript.font-shape = #'italic
\override Voice.TextScript.font-series = #'bold
d''2.^\markup "Allegro"
\override Voice.TextScript.font-size = #-3
c''4^"smaller"

[image of music]

A similar syntax may be used in markup mode; however, in most cases it is preferable to use the simpler syntax explained in Selecting font and font size: 

\markup {
  \column {
    \line {
      \override #'((font-shape . italic) (font-size . 4))
      Idomeneo,
    }
    \line {
      \override #'(font-family . typewriter) {
        \override #'(font-series . bold) re
        di
      }
      \override #'(font-family . sans) Creta
    }
  }
}

[image of music]

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

Font features

When using OpenType fonts, font features can be used.2 Note that not all OpenType fonts have all features. If you request a feature that does not exist in the chosen font, the feature is simply ignored. The example below uses the font ‘TeX Gyre Schola’ (this is, the roman style of the family). 

\markup { \override #'(font-name . "TeX Gyre Schola")
          normal style: Hello HELLO }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \caps { small caps: Hello } }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("smcp"))
          { true small caps: Hello } }

\markup { \override #'(font-name . "TeX Gyre Schola")
          normal number style: 0123456789 }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("onum"))
          { old number style: 0123456789 } }

\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("salt 0"))
          { stylistic alternate 0: εφπρθ } }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("salt 1"))
          { stylistic alternate 1: εφπρθ } }

\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("onum" "smcp" "salt 1"))
          { multiple features: Hello 0123456789 εφπρθ } }

[image of music]

For the full OpenType font feature list see https://www.microsoft.com/typography/otspec/featurelist.htm; for identifying features of OpenType fonts see https://lists.gnu.org/archive/html/lilypond-devel/2017-08/msg00004.html.

Although it is easy to switch between preconfigured fonts, it is also possible to use other fonts. For more information, see Single entry fonts and Entire document fonts.

See also

Notation Reference: The Emmentaler font, Music notation inside markup, Rotating objects, Selecting font and font size, Font.

[ << 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.3 

[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.

[ << Musical notation ][Top][Contents][Index][ Specialist notation >> ]
[ < Single entry fonts ][ Up : Fonts ][]

Entire document fonts

It is possible to change the fonts used in LilyPond’s default font families by calling the function make-pango-font-tree. The arguments are substitutions for the ‘roman’, ‘sans’ and ‘typewriter’ font families (in that order), followed by a scaling factor. Similar to single fonts (see Single entry fonts), font families are set up by using comma-separated lists of font family names, but without style options.4

Note that make-pango-font-tree resets the notation fonts to ‘emmentaler’ as the default.

The example below adjusts the font size in relation to the global staff size. 

\paper {
  #(define fonts
    (make-pango-font-tree "Linux Libertine O"
                          "Nimbus Sans, Nimbus Sans L"
                          "DejaVu Sans Mono"
                          (/ staff-height pt 20)))
}

\relative c'{
  c1-\markup {
    roman,
    \sans sans,
    \typewriter typewriter. }
}

[image of music]

LilyPond provides an alternative, more flexible interface to set global font families. It allows you to change only specific font family names, leaving others set to default values. The following example has the same effect as the above make-pango-font-tree example; the syntax for font family names is identical. If you do not change the staff size from the default of 20pt, the line containing the #:factor keyword is unnecessary. 

\paper {
  #(define fonts
    (set-global-fonts
     #:roman "Linux Libertine O"
     #:sans "Nimbus Sans, Nimbus Sans L"
     #:typewriter "DejaVu Sans Mono"
     ; unnecessary if the staff size is default
     #:factor (/ staff-height pt 20)
    ))
}

Additionally, set-global-fonts can also set the music notation fonts. The following example has the same effect as the previous examples, because it uses the default notation fonts. For more information, see Replacing the notation font. 

\paper {
  #(define fonts
    (set-global-fonts
     #:music "emmentaler"            ; default
     #:brace "emmentaler"            ; default
     #:roman "Linux Libertine O"
     #:sans "Nimbus Sans, Nimbus Sans L"
     #:typewriter "DejaVu Sans Mono"
     ; unnecessary if the staff size is default
     #:factor (/ staff-height pt 20)
    ))
}

Note that each call to set-global-fonts completely resets both the main notation and text fonts.5 If any font category is left unspecified, the respective default font (family) gets used for that category. Each call of set-global-fonts affects all \book blocks that follow it. If there are multiple \book blocks and you want to use different fonts for each, simply call set-global-fonts again, like this: 

\paper {
  #(define fonts
    (set-global-fonts
     …
    ))
}
\book {
  …
}

\paper {
  #(define fonts
    (set-global-fonts
     …
    ))
}
\book {
  …
}

See also

Notation Reference: Finding fonts, Font families, Single entry fonts, Selecting font and font size, Font, Replacing the notation font.

[ << Musical notation ][Top][Contents][Index][ Specialist notation >> ]
[ < Entire document fonts ][ Up : Fonts ][]

Music fonts

LilyPond neither uses FontConfig nor Pango for accessing music notation fonts but handles them by itself. As a consequence, the interface is different. This section describes how to insert music symbols into markup strings.

Music notation fonts are a collection of specific glyphs that can be accessed with several encodings. The following syntax allows LilyPond’s various Emmentaler glyphs6 to be used directly in markup mode: 

a'1^\markup {
  \vcenter {
    \override #'(font-encoding . fetaBraces)
    \lookup "brace120"
    \override #'(font-encoding . fetaText)
    \column { 1 3 sf }
    \override #'(font-encoding . fetaMusic)
    \lookup "noteheads.s0petrucci"
  }
}

[image of music]

However, all these glyphs except the braces of various sizes are available using the simpler syntax described in Music notation inside markup.

When accessing braces with the ‘fetaBraces’ encoding, the size of the brace is specified by the numerical part of the glyph name, in arbitrary units. Any integer from 0 to 575 inclusive may be specified, with 0 giving the smallest brace. The optimum value must be determined by trial and error. These glyphs are all left braces; right braces may be obtained by rotation, see Rotating objects.

Footnotes

[1] In its simplest form, a font family usually contains fonts in roman, italic, bold, and bold italic styles.

[2] Selecting OpenType font scripts and languages is not supported yet.

[3] 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.

[4] This implies that, contrary to single fonts, a trailing comma is never necessary.

[5] To be more precise, ‘emmentaler’ (with a lowercase ‘e’, which is mandatory in the argument to #:music and #:brace) is a set of fonts (but not a font family in the FontConfig sense) that LilyPond accesses and manages directly. Instead of various styles, however, it comes with different design sizes, see Music fonts and Replacing the notation font. The corresponding FontConfig font names are ‘Emmentaler-size’, where size is one of the numbers 11, 13, 14, 16, 18, 20, 23, and 26.

For braces, the FontConfig font name is ‘Emmentaler-Brace’.

[6] LilyPond’s Emmentaler fonts contain three glyph sets: Feta (for modern notation), Parmesan (for ancient notation), and braces. Both Feta and Parmesan are accessed with the ‘fetaMusic’ encoding.

[ << Musical notation ][Top][Contents][Index][ Specialist notation >> ]
[ < Entire document fonts ][ Up : Fonts ][]

<< Back to Documentation Index

LilyPond — Notation Reference v2.24.4 (stable-branch).