LilyPond Notation Reference: 1.8.1 Writing text

### 1.8.1 Writing text

This section introduces different ways of adding text to a score.

Note: To write accented and special text (such as characters from other languages), simply insert the characters directly into the LilyPond file. The file must be saved as UTF-8. For more information, see Text encoding.

#### Text objects overview

Simple text objects are entered as strings between double quotes (these are optional for a single word). The markup mode is a richer tool that can accept a variety of advanced text formatting and graphical enhancements, as detailed in Formatting text.

As such, markup blocks may be used:

- in any `TextScript` object (attached to notes with `-`, `^` or `_`); see Text scripts;
- as ‘spanners’, when some indications are prolonged over several beats or bars; see Text spanners;
- in any mark printed above the score, such as `RehearsalMark` or `MetronomeMark` objects respectively introduced with the `\mark` or `\tempo` keywords; see Text marks;
- as stand-alone text blocks, entered at the top level outside of any `\score` block (in this specific case the `\markup` or `\markuplist` command is mandatory, and cannot be omitted in favor of a simple text string between double quotes); see Separate text;
- in any definition inside the `\header` block (e.g., `title`, `subtitle`, `composer`), or in specific elements defined inside the `\paper` block such as `evenHeaderMarkup` for page numbers. This is explained in Titles and headers.

Many other text-based objects may be entered as markup blocks, even if that is not their primary use.

- Fingerings may easily be replaced with markup blocks, if introduced with the `\finger` command; see Fingering instructions.
- Lyric syllables may be formatted through the `\markup` command; see Common notation for vocal music.
- Chord names are in fact defined as markup blocks, and therefore may be redefined in the same way for customizing chord modifiers or chord exceptions; see Displaying chords.
- Dynamics are usually entered in a simple way; however it is possible to define New dynamic marks as markup objects. Some dynamics such as crescendo are printed as spanners and may be redefined through properties such as `crescendoText`; see Dynamics.
- Less common objects are also made of markup blocks, such as Balloon help indications.

In fact, it is possible to use `\markup` to customize the appearance of virtually any graphical object (or ‘grob’), by overriding either its `text` property if it has one, or its `stencil` property. Some of the logic that makes this a possibility is explained in Flexible architecture.

The following example illustrates the ubiquity of markup blocks, not only as some of the objects listed above, but also by replacing musical objects with text objects through various methods.

>     \header { title = \markup "Header" }

>     dyn =
>     #(make-dynamic-script #{ \markup \text "DynamicText" #})

>     \markup \box "Top-level markup"

>     \score {
>       <<
>         \new ChordNames
>         \with {
>           majorSevenSymbol = \markup "majorSevenSymbol"
>         }
>         \chordmode { c1:maj7 }
>         \new Staff {
>           \tempo \markup "MetronomeMark"
>           \textMark "TextMark"
>           \once \override TupletNumber.text =
>             \markup "TupletNumber"
>           \tuplet 3/2 {
>             \once \override NoteHead.stencil =
>               #ly:text-interface::print
>             \once \override NoteHead.text =
>               \markup \lower #0.5 "NoteHead"
>             c''8^\markup \italic "TextScript"
>             a'\finger \markup \text "Fingering"
>             \once \override Rest.stencil =
>               #(lambda (grob)
>                  (grob-interpret-markup grob #{
>                    \markup  "Rest"
>                    #}))
>             r
>           }
>         }
>         \new Lyrics \lyricmode {
>           \markup \smallCaps "LyricText" 1
>         }
>         \new Dynamics { s1\dyn }
>       >>
>     }

#### See also

Notation Reference: Formatting text, Text scripts, Text spanners, Text marks, Separate text, Fingering instructions, Common notation for vocal music, Displaying chords, New dynamic marks, Dynamics, Balloon help.

Essay on automated music engraving: Flexible architecture.

Snippets: Text.

#### Text scripts

Simple “quoted text” indications may be added to a score, as demonstrated in the following example. Such indications may be manually placed above or below the staff, using the syntax described in Direction and placement.

>     \relative { a'8^"pizz." g f e a4-"scherz." f }

This syntax is actually a shorthand; more complex text formatting may be added to a note by explicitly using a `\markup` block, as described in Formatting text.

>     \relative {
>       a'8^\markup { \italic pizz. } g f e
>       a4_\markup { \tiny scherz. \bold molto } f }

By default, text indications do not influence the note spacing. However, their widths can be taken into account: in the following example, the first text string does not affect spacing, whereas the second one does.

>     \relative {
>       a'8^"pizz." g f e
>       \textLengthOn
>       a4_"scherzando" f
>     }

In addition to text scripts, articulations can be attached to notes. For more information, see Articulations and ornamentations.

For more information about the relative ordering of text scripts and articulations, see Placement of objects.

#### Predefined commands

`\textLengthOn`, `\textLengthOff`.

#### See also

Learning Manual: Placement of objects.

Notation Reference: Formatting text, Direction and placement, Articulations and ornamentations.

Snippets: Text.

Internals Reference: TextScript.

#### Known issues and warnings

Checking to make sure that text scripts and lyrics are within the margins requires additional calculations. In cases where slightly faster performance is desired, use

>     \override Score.PaperColumn.keep-inside-line = ##f

#### Text spanners

Some performance indications, e.g., rallentando or accelerando, are written as text and are extended over multiple notes with dotted lines. Such objects, called “spanners”, may be created from one note to another using the following syntax:

>     \relative {
>       \override TextSpanner.bound-details.left.text = "rit."
>       b'1\startTextSpan
>       e,\stopTextSpan
>     }

The string to be printed is set through object properties. By default it is printed in italic characters, but different formatting can be obtained using `\markup` blocks, as described in Formatting text.

>     \relative {
>       \override TextSpanner.bound-details.left.text =
>         \markup { \upright "rit." }
>       b'1\startTextSpan c
>       e,\stopTextSpan
>     }

The line style, as well as the text string, can be defined as an object property. This syntax is described in Line styles.

#### Predefined commands

`\textSpannerUp`, `\textSpannerDown`, `\textSpannerNeutral`.

#### Known issues and warnings

LilyPond is only able to handle one text spanner per voice.

The texts at the bounds of a text spanner may collide.

>     {
>       \once \override TextSpanner.bound-details.left.text = "The text is"
>       \once \override TextSpanner.bound-details.right.text = "too long"
>       c'2\startTextSpan d'2\stopTextSpan
>     }

Workarounds can be found in Horizontal spacing.

#### Selected Snippets

#### Dynamics text spanner postfix

Custom text spanners can be defined and used with hairpin and text crescendos. `\<` and `\>` produce hairpins by default, `\cresc` etc. produce text spanners by default.

>     % Some sample text dynamic spanners, to be used as postfix operators
>     crpoco =
>     #(make-music 'CrescendoEvent
>                  'span-direction START
>                  'span-type 'text
>                  'span-text "cresc. poco a poco")

>     \relative c' {
>       c4\cresc d4 e4 f4 |
>       g4 a4\! b4\crpoco c4 |
>       c4 d4 e4 f4 |
>       g4 a4\! b4\< c4 |
>       g4\dim a4 b4\decresc c4\!
>     }

#### Dynamics custom text spanner postfix

Postfix functions for custom crescendo text spanners. The spanners should start on the first note of the measure. One has to use `-\mycresc`, otherwise the spanner start will rather be assigned to the next note.

>     % Two functions for (de)crescendo spanners where you can explicitly
>     % give the spanner text.
>     mycresc =
>     #(define-music-function (mymarkup) (markup?)
>        (make-music 'CrescendoEvent
>                    'span-direction START
>                    'span-type 'text
>                    'span-text mymarkup))
>     mydecresc =
>     #(define-music-function (mymarkup) (markup?)
>        (make-music 'DecrescendoEvent
>                    'span-direction START
>                    'span-type 'text
>                    'span-text mymarkup))

>     \relative c' {
>       c4-\mycresc "custom cresc" c4 c4 c4 |
>       c4 c4 c4 c4 |
>       c4-\mydecresc "custom decresc" c4 c4 c4 |
>       c4 c4\! c4 c4
>     }

#### See also

Notation Reference: Line styles, Dynamics, Formatting text.

Snippets: Text, Expressive marks.

Internals Reference: TextSpanner.

#### Section labels

The `\sectionLabel` command marks the beginning of a named passage. It is well suited for use at a section division created with `\section`, but it does not imply `\section` and may be used alone.

>     \fixed c' {
>       \sectionLabel "Verse"
>       c2 g
>       \section
>       \sectionLabel "Chorus"
>       g2 c
>       \bar "|."
>     }

#### See also

Notation Reference: Formatting text, Rehearsal marks, Section divisions.

Snippets: Text.

Internals Reference: SectionLabel, SectionLabelEvent.

#### Text marks

Text marks are textual objects that, unlike text scripts (see Text scripts), are not printed over notes but between notes, often aligned to a bar line.

Note: Older LilyPond versions used the `\mark` command for text marks, even though it is primarily intended for rehearsal marks (see Rehearsal marks). The `\textMark` and `\textEndMark` commands are better suited for text marks with regard to their default settings as well as the ability to have several text marks at the same moment. It is therefore recommended to use `\textMark` and `\textEndMark` instead of `\mark "Text"` or `\mark \markup …`. Note that if converting code that uses `\mark` for text marks, overrides using `RehearsalMark` should be changed to `TextMark`.

Before using text marks, it is recommended to seek a more specific command, if available. For text that identifies a section, use `\sectionLabel` (see Section labels). For jump instructions, use `\jump` (see Manual repeat marks). These commands have different default layout settings, and they create separate objects which can be styled differently from generic text marks in stylesheets.

A text mark is entered using either `\textMark` or `\textEndMark`. The `\textMark` command draws a left-aligned mark.

>     \fixed c'' {
>       \textMark "Fl. 1 solo"
>       c4 e g2
>       \textMark "A due"
>       e4 g c'2
>     }

If a line break occurs at the point `\textMark` is used, the text appears on the next system.

>     \fixed c'' {
>       \textMark "Fl. 1 solo"
>       c4 e g2
>       \break
>       \textMark "A due"
>       e4 g c'2
>     }

Unlike `\textMark`, `\textEndMark` creates a right-aligned mark. If it occurs on a line break, it is printed on the preceding system.

>     \fixed c' {
>       \repeat volta 2 {
>         c4 e8 f g2
>         e4 f8 g c'2
>         \textEndMark "ad lib"
>       }
>       \break
>       c'4 8 8 4 8 8
>       c'1
>     }

Complex text formatting may be added using a `\markup` block (see Formatting text).

>     \relative {
>       <c' e>1
>       \textMark \markup { \italic { colla parte } }
>       <d f>2 <e g>
>       <c f aes>1
>     }

The `\markLengthOn` and `\markLengthOff` commands (see Metronome marks) can also be used on text marks.

>     {
>       \mark \default
>       c'2 2
>       \textEndMark "long mark text"
>       \markLengthOn
>       2 2
>       \mark \default
>       2 2
>       \textEndMark "long mark text"
>     }

Text marks may be printed below the staff.

>     \fixed c' {
>       c4 g c'8 b c4 e' c' c2
>       c4 g c'8 b c4 e' c' g2
>       e'4 c' c'8 b c'4
>       g4 c' c2~ c1
>       \tweak direction #DOWN
>         \tweak font-size #-1
>           \textEndMark "Composed on November 13th, 2020"
>     }

There can be several text marks at the same moment. Their stacking order can be overridden using the `outside-staff-priority` property (see Vertical collision avoidance). Alternatively, a single text mark with `\markup \column { … }` can achieve the same effect.

>     \fixed c' {
>       \repeat volta 2 {
>         c4 g c'8 b c4 e' c' c2
>         \textEndMark "ad lib."
>         \tweak outside-staff-priority 1200
>           \tweak font-size -1
>             \textEndMark "2nd time a due"
>       }
>     }

The alignment of a text mark can be changed.

>     {
>       c'8 8 8 8 8 8 8 8
>       \textMark \markup \column {
>         \line { Left-aligned mark }
>         \line { (default for \concat { \typewriter "\\textMark" ) } }
>       }
>       d'8 8 8 8 8 8 8 8
>     }

>     {
>       c'8 8 8 8 8 8 8 8
>       \tweak self-alignment-X #CENTER
>         \textMark "Centered mark"
>       d'8 8 8 8 8 8 8 8
>     }

>     {
>       c'8 8 8 8 8 8 8 8
>       \tweak self-alignment-X #RIGHT
>         \textMark \markup \right-column {
>           \line { Right-aligned mark }
>           \line { (default for \concat { \typewriter "\\textEndMark" ) } }
>         }
>       d'8 8 8 8 8 8 8 8
>     }

#### Predefined commands

`\textMark`, `\textEndMark`, `\markLengthOn`, `\markLengthOff`.

#### Selected Snippets

#### Printing marks on every staff

Although marks are normally only printed above the topmost staff, they may also be printed on every staff.

>     \score {
>       <<
>         \new Staff { \mark \default c''1 \textMark "molto" c'' }
>         \new Staff { \mark \default c'1 \textMark "molto" c' }
>       >>
>       \layout {
>         \context {
>           \Score
>           \remove Mark_engraver
>           \remove Text_mark_engraver
>           \remove Staff_collecting_engraver
>         }
>         \context {
>           \Staff
>           \consists Mark_engraver
>           \consists Text_mark_engraver
>           \consists Staff_collecting_engraver
>         }
>       }
>     }

#### See also

Notation Reference: Metronome marks, Rehearsal marks, Section labels, Formatting text, Music notation inside markup, The Emmentaler font.

Snippets: Text.

Internals Reference: TextMarkEvent, Text_mark_engraver, TextMark.

#### Separate text

A `\markup` or `\markuplist` block can exist by itself, outside of any `\score` block, as a “top-level expression”. This syntax is described in File structure.

>     \markup {
>       Tomorrow, and tomorrow, and tomorrow...
>     }

This allows printing text separately from the music, which is particularly useful when the input file contains several music pieces, as described in Multiple scores in a book.

>     \score {
>       c'1
>     }
>     \markup {
>       Tomorrow, and tomorrow, and tomorrow...
>     }
>     \score {
>       c'1
>     }

Using `\markuplist`, separate text blocks can be spread over multiple pages, making it possible to print text documents or books entirely within LilyPond. For a description of this feature and the specific syntax it requires, see Text markup introduction.

#### Predefined commands

`\markup`, `\markuplist`.

#### Selected Snippets

#### Stand-alone two-column markup

Stand-alone text may be arranged in several columns using `\markup` commands:

>     \markup {
>       \fill-line {
>         \hspace #1
>         \column {
>           \line { O sacrum convivium }
>           \line { in quo Christus sumitur, }
>           \line { recolitur memoria passionis ejus, }
>           \line { mens impletur gratia, }
>           \line { futurae gloriae nobis pignus datur. }
>           \line { Amen. }
>         }
>         \hspace #2
>         \column \italic {
>           \line { O sacred feast }
>           \line { in which Christ is received, }
>           \line { the memory of His Passion is renewed, }
>           \line { the mind is filled with grace, }
>           \line { and a pledge of future glory is given to us. }
>           \line { Amen. }
>         }
>         \hspace #1
>       }
>     }

#### See also

Notation Reference: Formatting text, File structure, Multiple scores in a book.

Snippets: Text.

Internals Reference: TextScript.

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