LilyPond Notation Reference: 1.8.3 Fonts

### 1.8.3 Fonts

This section presents the way fonts are handled, and how they may be changed in scores.

#### Fonts explained

Fonts are handled through several libraries. FontConfig is used to detect available fonts; the selected fonts are rendered using Pango.

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

>     #(ly:font-config-add-font "path/to/font-file.otf")

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

Both of these commands accept either absolute or relative paths, which makes it possible to compile a score on any system by simply copying the relevant font files alongside the source code.

Having been detected, fonts must then be selected using the methods described in Single entry fonts and Entire document fonts. As it prints the complete list of available fonts in the console log, the command `#(ly:font-config-display-fonts)` may be of use to verify which fonts are indeed detected, and under which names (as these may differ from the file names themselves).

Music notation fonts can be described as a set of specific glyphs, ordered in several families. The following syntax allows LilyPond’s various Feta glyphs 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"
>       }
>     }

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

When using the glyphs contained in `fetaBraces`, 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, `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.

Three families of text fonts are made available: the roman (serif) font, the sans font, and the typewriter font.

For `svg` backend:

Family | Default font
--- | ---
roman | `serif`
sans | `sans-serif`
typewriter | `monospace`

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

For other backends:

Family | Default font (alias) | Alias definition lists
--- | --- | ---
roman | `LilyPond Serif` | C059, Century SchoolBook URW, Century Schoolbook L, TeX Gyre Schola, DejaVu Serif, ..., serif
sans | `LilyPond Sans Serif` | Nimbus Sans, Nimbus Sans L, TeX Gyre Heros, DejaVu Sans, ..., sans-serif
typewriter | `LilyPond Monospace` | Nimbus Mono PS, Nimbus Mono, Nimbus Mono L, TeX Gyre Cursor, DejaVu Sans Mono, ..., monospace

Note that the URW fonts distributed with LilyPond (‘C059’, ‘Nimbus Mono PS’, and ‘Nimbus Sans’) 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 aliases defined in the LilyPond dedicated FontConfig configuration file `00-lilypond-fonts.conf`. Where a character doesn’t exist in the first font listed, the next font listed will be used instead for that character. For details of alias definitions, please see to `00-lilypond-fonts.conf` under the installed directory.

Each family may include different shapes and series. The following example demonstrates the ability to select alternate families, shapes, series and sizes. The value supplied to `font-size` is the required change from the default size.

>     \override Score.RehearsalMark.font-family = #'typewriter
>     \mark \markup "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

A similar syntax may be used in markup mode; however in this case 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
>         }
>       }
>     }

When using OpenType fonts, font features can be used. OpenType font scripts and languages can not be specified. Note: Not all OpenType fonts have all features. If you request a feature that doesn’t exist in the chosen font, then the feature is simply ignored. These examples use TeX Gyre Schola.

>     % True small caps
>     \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 } }

>     % Number styles
>     \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 } }

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

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

For the full OpenType font feature list please see: https://www.microsoft.com/typography/otspec/featurelist.htm

For identifying features of OpenType fonts please see: http://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, as explained in the following sections: 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.

#### Single entry fonts

Any font that is installed on the operating system and recognized by FontConfig may be used in a score, using the following syntax:

>     \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 }
>     }

font-name can be described using a comma-separated list of ‘fonts’ and a white-space separated list of ‘styles’. As long as the ‘font’ in the list is installed and contains requested glyph, it will be used, otherwise the next font in the list will be used instead.

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

>     lilypond -dshow-available-fonts

#### See also

Notation Reference: Fonts explained, Entire document fonts.

Snippets: Text.

#### Entire document fonts

It is possible to change the fonts to be used as the default fonts in the roman, sans and typewriter font families by specifying them, in that order, as shown in the example below, which automatically scales the fonts with the value set for the global staff size. Similar to Single entry fonts, it can be described using a comma-separated list of ‘fonts’. However, font ‘styles’ can not be described. For an explanation of fonts, see Fonts explained.

>     \paper  {
>       #(define fonts
>         (make-pango-font-tree "Times New Roman"
>                               "Nimbus Sans,Nimbus Sans L"
>                               "Luxi Mono"
>                               (/ staff-height pt 20)))
>     }

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

Note: `make-pango-font-tree` resets the notation fonts to default of Emmentaler.

The following syntax allows you to change the specific fonts, leaving others to the default values. The following example has the same effect as the above `make-pango-font-tree` example. The same as `make-pango-font-tree`, you can specify a comma-separated list of ‘fonts’ for `roman`, `sans`, and `typewriter` categories. If you don’t change the staff size from the default of 20 pt, `#:factor (/ staff-height pt 20)` is unnecessary.

>     \paper {
>       #(define fonts
>         (set-global-fonts
>          #:roman "Times New Roman"
>          #:sans "Nimbus Sans,Nimbus Sans L"
>          #:typewriter "Luxi Mono"
>          ; unnecessary if the staff size is default
>          #:factor (/ staff-height pt 20)
>         ))
>     }

It also can specify the notation fonts. The following example also has the same effect as the above examples, because it sets the notation fonts as the default. For more information, see Replacing the notation font.

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

Note: Each call to `set-global-fonts` completely resets both the main notation and text fonts. If any category is left unspecified, then the default font will be used for that category. Each call of `set-global-fonts` affects each `\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: Fonts explained, Single entry fonts, Selecting font and font size, Font, Replacing the notation font.

#### LilyPond — Notation Reference v2.22.2 (stable-branch).