22.2.1 Using variables

If sections of the music are defined in variables they can be reused in different parts of the score, see Organizing pieces with variables. For example, an a cappella vocal score frequently includes a piano reduction of the parts for rehearsal purposes which is identical to the vocal music, so the music need be entered only once. Music from two variables may be combined on one staff, see Automatic part combining. Here is an example:

sopranoMusic = \relative { a'4 b c b8( a) }
altoMusic = \relative { e'4 e e f }
tenorMusic = \relative { c'4 b e d8( c) }
bassMusic = \relative { a4 gis a d, }
allLyrics = \lyricmode { King of glo -- ry }
<<
  \new Staff = "Soprano" \sopranoMusic
  \new Lyrics \allLyrics
  \new Staff = "Alto" \altoMusic
  \new Lyrics \allLyrics
  \new Staff = "Tenor" {
    \clef "treble_8"
    \tenorMusic
  }
  \new Lyrics \allLyrics
  \new Staff = "Bass" {
    \clef "bass"
    \bassMusic
  }
  \new Lyrics \allLyrics
  \new PianoStaff <<
    \new Staff = "RH" {
      \partCombine \sopranoMusic \altoMusic
    }
    \new Staff = "LH" {
      \clef "bass"
      \partCombine \tenorMusic \bassMusic
    }
  >>
>>

Separate scores showing just the vocal parts or just the piano part can be produced by changing just the structural statements, leaving the musical notation unchanged.

For lengthy scores, the variable definitions may be placed in separate files which are then included, see Including LilyPond files.

22.2.2 Using tags

The \tag command marks a music expression with a name.

\tag #'foo { ... }

Expressions tagged in this way can be conviently manipulated as a whole.

Keeping and removing tagged music

The command \keepWithTag selects tagged music. On the other hand, \removeWithTag filters out tagged music.

Filter	Result
Tagged music preceded by \keepWithTag #'name or \keepWithTag #'(name1 name2…)	Untagged music and music tagged with any of the given tag names is included; music tagged with any other tag name is excluded.
Tagged music preceded by \removeWithTag #'name or \removeWithTag #'(name1 name2…)	Untagged music and music not tagged with any of the given tag names is included; music tagged with any of the given tag names is excluded.
Tagged music not preceded by either \keepWithTag or \removeWithTag	All tagged and untagged music is included.

The arguments of the \tag, \keepWithTag, and \removeWithTag commands should be a symbol or a list of symbols such as #'score or #'(violinI violinII), followed by a music expression. If and only if the symbols are valid LilyPond identifiers (alphabetic characters only, no numbers, underscores, or dashes, and different from any note names), the #' prefix may be omitted and, as a shorthand, a list of symbols can use the comma separator. For example, \tag #'(violinI violinII) can be written as \tag violinI,violinII. The same applies to the arguments of \keepWithTag and \removeWithTag.

Tagging commands are music functions, thus they cannot be used to filter items that are not music expressions, such as \book or \score blocks.

In the following example, we see two versions of a piece of music, one showing trills with the usual notation, and one with trills explicitly expanded.

music = \relative {
  g'8. c32 d
  \tag #'trills { d8.\trill }
  \tag #'expand { \repeat unfold 3 { e32 d } }
  c32 d
 }

\score {
  \keepWithTag #'trills \music
}
\score {
  \keepWithTag #'expand \music
}

Alternatively, it is sometimes easier to exclude sections of music.

music = \relative {
  g'8. c32 d
  \tag #'trills { d8.\trill }
  \tag #'expand { \repeat unfold 3 { e32 d } }
  c32 d
 }

\score {
  \removeWithTag #'expand \music
}
\score {
  \removeWithTag #'trills \music
}

If tags mark alternatives that have non-zero duration, the alternatives are often conceptually simultaneous. In this case it is best to put the alternatives in a simultaneous music expression so that the music expression has the same duration no matter which tags are retained. This is especially important if you are using tags in combination with commands like \cueDuring.

outputTypeTag = "isScore"

firstInstrument = \relative c' {
  <<
    \tag #'isPart {
      \cueDuring "quoteSecondInstrument" #UP { r2 } }
    \tag #'isScore { r2 }
  >>
  e4 f |
  g4 a b c |
}

secondInstrument= \relative c'' {
  c4 c r2 |
  \cueDuring "quoteFirstInstrument" #DOWN { r2 }
  c4 c |
}

\addQuote quoteFirstInstrument \firstInstrument
\addQuote quoteSecondInstrument \secondInstrument

\new Staff {
  \keepWithTag \outputTypeTag \firstInstrument
}

\new Staff {
  \keepWithTag \outputTypeTag \secondInstrument
}

Tagged filtering can be applied to articulations, texts, etc., by prepending

-\tag #'your-tag

to an articulation. For example, the following defines a note with a conditional fingering indication and a note with a conditional annotation.

c1-\tag #'finger ^4
c1-\tag #'warn ^"Watch!"

Multiple tags may be placed on expressions with multiple \tag entries, or by combining multiple tags into one symbol list.

music = \relative c'' {
  \tag AA \tag AB { a4 a a a }
  \tag BB,both { b4 b b b }
}

<<
  \keepWithTag AA \music
  \keepWithTag BB \music
  \keepWithTag AB \music
>>

Multiple \removeWithTag filters may be applied to a single music expression to remove several differently named tagged sections. Alternatively, you can use a single \removeWithTag with a list of tags.

music = \relative c'' {
  \tag AA { a4 a a a }
  \tag BB { b4 b b b }
  \tag CC { c4 c c c }
  \tag DD { d4 d d d }
}

\new Voice {
  \removeWithTag BB \removeWithTag CC \music
  \removeWithTag BB,CC \music
}

Using two or more \keepWithTag filters on a single music expression causes all of the tagged sections to be removed, which is certainly not what you want: the first filter removes everything except the one named, and any subsequent filter removes the rest. Instead, use one \keepWithTag command with a list of multiple tags to remove all tagged sections that are not specified in that list. As an example, the following code prints music tagged with violinI and violinII but not tagged with viola or cello.

music = \relative c'' {
  \tag violinI { a4 a a a }
  \tag violinII { b4 b b b }
  \tag viola { c4 c c c }
  \tag cello { d4 d d d }
}

\new Staff {
  \keepWithTag violinI,violinII \music
}

While \keepWithTag is convenient when dealing with one set of alternatives, the removal of music tagged with unrelated tags is problematic when using them for more than one purpose. In that case tags can be grouped with \tagGroup. The following code

\tagGroup violinI,violinII,viola,cello

puts the four tags into a single tag group. As a result, code like

\keepWithTag violinI …

now only shows music tagged from violinI’s tag group; any music tagged with one of the other tags in the group is removed, as the following example demonstrates.

\tagGroup violinI,violinII
\tagGroup original,arranged

music = \relative {
  \tag violinI { c''4^"violinI" c c c }
  \tag violinII { a2 a }
  \tag original { e8 e e2. }
  \tag arranged { d'2 d4 d }
  \tag other { f^"other" f f f }
  R1^"untagged"
}

\new Voice {
  \keepWithTag violinI \music
}

Note that individual tags cannot be members of more than one tag group.

Prepending and appending to tagged music

Sometimes you want to splice some music at a particular place in an existing music expression. You can use \pushToTag and \appendToTag to add material at the front and end of various music constructs, respectively. The supported places are

sequential and simultaneous music

If you tag an entire {…} or <<…>> construct, you can add music expressions at its front or back.

chords

If you tag a chord <…>, you can either add notes at its front or back, or articulations for the whole chord.

notes and rests

If you tag a note (also inside of a chord) or a rest, you can add articulations to the front or back of its existing articulations. Note that to add other notes, you have to put the note inside of a chord and tag the chord instead.

Also note that you cannot tag a single articulation and add to it since it isn’t inherently a list. Instead, tag the note.

Both commands get a tag, the material to splice in at every occurrence of the tag, and the tagged expression.

music = { \tag #'here { \tag #'here <<c''>> } }

{
  \pushToTag #'here c'
  \pushToTag #'here e'
  \pushToTag #'here g' \music
  \appendToTag #'here c'
  \appendToTag #'here e'
  \appendToTag #'here g' \music
}

Tagging within markups

The \tag command can also be used within \markup. LilyPond provides markup commands \keep-with-tag, \remove-with-tag, \push-to-tag, and \append-to-tag in analogy to the corresponding commands for music expressions.

test = \markup {
  \tag #'AA a
  \tag #'BB b
  \tag #'CC c
}

\markup { \keep-with-tag #'BB \test }
\markup { \remove-with-tag #'BB \test }
\markup { \push-to-tag #'CC pre \test }
\markup { \append-to-tag #'CC post \test }

Music commands like \keepWithTag and \removeWithTag filter tags in \markup parts in the related music, too.

music = \relative {
  c'4^\markup { \tag #'one first \tag #'two second part } c c c
}

{
  \keepWithTag #'one \music
  \removeWithTag #'one \music
}

It is also possible to push and append something to the \markup of musical objects. However, we cannot use \pushToTag and \appendToTag because they only insert some music, so we need commands \pushToTagMarkup and \appendToTagMarkup to insert markup.

music = \relative {
  c'4^\markup { \tag #'part part } c c c
}

{
  \pushToTagMarkup #'part "great" \music
  \appendToTagMarkup #'part \markup { is also great } \music
}

The filtering of tags also works for music embedded within \score blocks in markup commands.

music = \relative {
  c'2^\markup { \tag #'first first \tag #'second second } c
  \tag #'first { d d }
  \tag #'second { f f }
}

\markup {
  \keep-with-tag #'first \score { \music }
  \remove-with-tag #'first \score { \music }
}

Tagging lists of markup need special attention. While the filter functions work as expected, commands like \push-to-tag and \append-to-tag do not.

\markup {
  \remove-with-tag #'test { a \tag #'test { b c } d }
}
\markup {
  \push-to-tag #'test "twice" { a \tag #'test { b c } d }
}

The reason for this behavior is that LilyPond resolves

\tag #'test { b c }

internally to

\tag #'test b
\tag #'test c

and thus the given text is inserted twice. For tagging a list to insert or append something before or after the whole list the command \tag-list should be used.

\markup {
  \push-to-tag #'test "once" { a \tag-list #'test { b c } d }
}

See also

Learning Manual: Organizing pieces with variables.

Notation Reference: Automatic part combining, Including LilyPond files.

Known issues and warnings

Calling \relative on a music expression obtained by filtering music through \keepWithTag or \removeWithTag might cause the octave relations to change, as only the pitches actually remaining in the filtered expression are considered. Applying \relative first, before \keepWithTag or \removeWithTag, avoids this danger as \relative then acts on all the pitches as input.

Even when using tag groups, commands like \keepWithTag are not commutative. Code like

\keepWithTag violinI,original \someMusic

does not produce the same output as

\keepWithTag violinI \keepWithTag original \someMusic

22.2.3 Using global settings

Global settings can be included from a separate file:

lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly

Groups of settings such as page size, font or type face can be stored in separate files and loaded with several -dinclude-settings options. This allows different editions from the same score as well as standard settings to be applied to many scores, simply by specifying the proper settings file.

This technique also works well with the use of style sheets, as discussed in Style sheets.

See also

Learning Manual: Organizing pieces with variables, Style sheets.

Notation Reference: Including LilyPond files.