3.1 Input structure

The main format of input for LilyPond are text files. By convention, these files end with ‘.ly’.

3.1.1 Structure of a score

A \score block must contain a single music expression delimited by curly brackets:

\score {
  …
}

This single music expression may be of any size, and may contain other music expressions to any complexity. All of these examples are music expressions:

{ c'4 c' c' c' }

{ { c'4 c' c' c' } { d'4 d' d' d' } }

<< \new Staff { c'4 c' c' c' } \new Staff { d'4 d' d' d' } >>

{
  \new GrandStaff <<
    \new StaffGroup <<
      \new Staff { \flute }
      \new Staff { \oboe }
    >>
    \new StaffGroup <<
      \new Staff { \violinI }
      \new Staff { \violinII }
    >>
  >>
}

Comments are one exception to this general rule. (For others see File structure.) Both single-line comments and comments delimited by %{ … %} may be placed anywhere within an input file. They may be placed inside or outside a \score block, and inside or outside the single music expression within a \score block.

Remember that even in a file containing only a \score block, it is implicitly enclosed in a \book block. A \book block in a source file produces at least one output file, and by default the name of the output file produced is derived from the name of the input file, so ‘fandangoforelephants.ly’ will produce ‘fandangoforelephants.pdf’.

(For more details about \book blocks, see Multiple scores in a book, Multiple output files from one input file File structure.)

See also

Learning Manual: (learning)Working on input files section ‘Working on input files’ in Learning Manual, (learning)Music expressions explained section ‘Music expressions explained’ in Learning Manual, (learning)Score is a (single) compound musical expression section ‘Score is a (single) compound musical expression’ in Learning Manual.

3.1.2 Multiple scores in a book

A document may contain multiple pieces of music and text. Examples of these are an etude book, or an orchestral part with multiple movements. Each movement is entered with a \score block,

\score {
  …music…
}

and texts are entered with a \markup block,

\markup {
  …text…
}

All the movements and texts which appear in the same ‘.ly’ file will normally be typeset in the form of a single output file.

\score {
  …
}
\markup {
  …
}
\score {
  …
}

One important exception is within lilypond-book documents, where you explicitly have to add a \book block, otherwise only the first \score or \markup will appear in the output.

The header for each piece of music can be put inside the \score block. The piece name from the header will be printed before each movement. The title for the entire book can be put inside the \book, but if it is not present, the \header which is at the top of the file is inserted.

\header {
  title = "Eight miniatures"
  composer = "Igor Stravinsky"
}
\score {
  …
  \header { piece = "Romanze" }
}
\markup {
   …text of second verse…
}
\markup {
   …text of third verse…
}
\score {
  …
  \header { piece = "Menuetto" }
}

Pieces of music may be grouped into book parts using \bookpart blocks. Book parts are separated by a page break, and can start with a title, like the book itself, by specifying a \header block.

\bookpart {
  \header {
    title = "Book title"
    subtitle = "First part"
  }
  \score { … }
  …
}
\bookpart {
  \header {
    subtitle = "Second part"
  }
  \score { … }
  …
}

3.1.3 Multiple output files from one input file

If you want multiple output files from the same ‘.ly’ file, then you can add multiple \book blocks, where each such \book block will result in a separate output file. If you do not specify any \book block in the input file, LilyPond will implicitly treat the whole file as a single \book block, see File structure.

When producing multiple files from a single source file, LilyPond ensures that none of the output files from any \book block overwrites the output file produced by a preceding \book from the same input file.

It does this by adding a suffix to the output name for each \book which uses the default output file name derived from the input source file.

The default behaviour is to append a version-number suffix for each name which may clash, so

\book {
  \score { … }
  \paper { … }
}
\book {
  \score { … }
  \paper { … }
}
\book {
  \score { … }
  \paper { … }
}

in source file ‘eightminiatures.ly’ will produce

• ‘eightminiatures.pdf’,
• ‘eightminiatures-1.pdf’ and
• ‘eightminiatures-2.pdf’.

3.1.4 Output file names

LilyPond provides facilities to allow you to control what file names are used by the various back-ends when producing output files.

In the previous section, we saw how LilyPond prevents name-clashes when producing several outputs from a single source file. You also have the ability to specify your own suffixes for each \book block, so for example you can produce files called ‘eightminiatures-Romanze.pdf’, ‘eightminiatures-Menuetto.pdf’ and ‘eightminiatures-Nocturne.pdf’ by adding a \bookOutputSuffix declaration inside each \book block.

\book {
  \bookOutputSuffix "Romanze"
  \score { … }
  \paper { … }
}
\book {
  \bookOutputSuffix "Menuetto"
  \score { … }
  \paper { … }
}
\book {
  \bookOutputSuffix "Nocturne"
  \score { … }
  \paper { … }
}

You can also specify a different output filename for book block, by using \bookOutputName declarations

\book {
  \bookOutputName "Romanze"
  \score { … }
  \paper { … }
}
\book {
  \bookOutputName "Menuetto"
  \score { … }
  \paper { … }
}
\book {
  \bookOutputName "Nocturne"
  \score { … }
  \paper { … }
}

The file above will produce these output files:

• ‘Romanze.pdf’,
• ‘Menuetto.pdf’ and
• ‘Nocturne.pdf’.

3.1.5 File structure

A ‘.ly’ file may contain any number of toplevel expressions, where a toplevel expression is one of the following:

• An output definition, such as \paper, \midi, and \layout. Such a definition at the toplevel changes the default book-wide settings. If more than one such definition of the same type is entered at the top level the definitions are combined, but in conflicting situations the later definitions take precedence. For details of how this affects the \layout block see The \layout block.
• A direct scheme expression, such as #(set-default-paper-size "a7" 'landscape) or #(ly:set-option 'point-and-click #f).
• A \header block. This sets the global (i.e., the top of file) header block. This is the block containing the default settings of titling fields like composer, title, etc., for all books within the file (see Titles explained).
• A \score block. This score will be collected with other toplevel scores, and combined as a single \book. This behavior can be changed by setting the variable toplevel-score-handler at toplevel. (The default handler is defined in the file ‘../scm/lily-library.scm’ and set in the file ‘../ly/declarations-init.ly’.)
• A \book block logically combines multiple movements (i.e., multiple \score blocks) in one document. If there are a number of \scores, one output file will be created for each \book block, in which all corresponding movements are concatenated. The only reason to explicitly specify \book blocks in a ‘.ly’ file is if you wish to create multiple output files from a single input file. One exception is within lilypond-book documents, where you explicitly have to add a \book block if you want more than a single \score or \markup in the same example. This behavior can be changed by setting the variable toplevel-book-handler at toplevel. The default handler is defined in the init file ‘../scm/lily.scm’.
• A \bookpart block. A book may be divided into several parts, using \bookpart blocks, in order to ease the page breaking, or to use different \paper settings in different parts.
• A compound music expression, such as

  { c'4 d' e'2 }

  This will add the piece in a \score and format it in a single book together with all other toplevel \scores and music expressions. In other words, a file containing only the above music expression will be translated into

  \book { \score { \new Staff { \new Voice { { c'4 d' e'2 } } } \layout { } } \paper { } \header { } }

  This behavior can be changed by setting the variable toplevel-music-handler at toplevel. The default handler is defined in the init file ‘../scm/lily.scm’.

• A markup text, a verse for example

  \markup { 2. The first line verse two. }

  Markup texts are rendered above, between or below the scores or music expressions, wherever they appear.

• A variable, such as

  foo = { c4 d e d }

  This can be used later on in the file by entering \foo. The name of a variable should not contain (ASCII) numbers, multiple underscores, multiple dashes or space characters. All other characters Unicode provides are allowed, for example Latin, Greek, Chinese or Cyrillic. Non-adjacent single underscores and dashes are allowed, too. In other words, variable names like HornIII or αβγXII work.

  Any combination of characters is allowed if the variable name is enclosed in double quotation marks. In this case backslashes and double quotation marks need to be escaped with backslashes (not that you actually should use them). Examples: "foo bar", "a-b-c", "Horn 3".

The following example shows three things that may be entered at toplevel

\layout {
  % Don't justify the output
  ragged-right = ##t
}

\header {
   title = "Do-re-mi"
}

{ c'4 d' e2 }

At any point in a file, any of the following lexical instructions can be entered:

• \version
• \include
• \sourcefilename
• \sourcefileline
• A single-line comment, introduced by a leading % sign.
• A multi-line comment delimited by %{ … %}.

Whitespace between items in the input stream is generally ignored, and may be freely omitted or extended to enhance readability. However, whitespace should always be used in the following circumstances to avoid errors:

• Around every opening and closing curly bracket.
• After every command or variable, i.e., every item that begins with a \ sign.
• After every item that is to be interpreted as a Scheme expression, i.e., every item that begins with a # sign.
• To separate all elements of a Scheme expression.
• In lyricmode before and after \set and \override commands.

See also

Learning Manual: (learning)How LilyPond input files work section ‘How LilyPond input files work’ in Learning Manual.

Notation Reference: Titles explained, The \layout block.

This document was generated by gub on July 13, 2020 using texi2html 1.82.

Other languages: català, deutsch, español, français, italiano, 日本語.
About automatic language selection.