LilyPond — Usage

1.1 Normal usage

Most users run LilyPond through a GUI; if you have not done so already, please read the Tutorial. If you use an alternate editor to write LilyPond files, see the documentation for that program.

1.2 Command-line usage

This section contains extra information about using LilyPond on the command line. This may be desirable to pass extra options to the program. In addition, there are certain extra ‘helper’ programs (such as midi2ly) which are only available on the command line.

By ‘command line’, we mean the command line in the operating system. Windows users might be more familiar with the terms ‘DOS shell’ or ‘command shell’. macOS users might be more familiar with the terms ‘terminal’ or ‘console’.

Describing how to use this part of an operating system is outside the scope of this manual; please consult other documentation on this topic if you are unfamiliar with the command line.

You should use a command line that reads and writes Unicode in UTF-8 encoding. Today, this is the standard on Unix-like operating systems including macOS and GNU/Linux. On Windows, you can select UTF-8 by selecting an appropriate codepage: call

chcp 65001

once on the command line before running lilypond.exe. Please consult the internet how to permanently activate UTF-8 for the Windows console.¹

/home/me/lilypond-2.25.22/bin

C:\Users\me\lilypond-2.25.22\bin

/home/me/lilypond-2.25.22/bin/lilypond music.ly

lilypond [option]… file…

lilypond *.ly

lilypond file.ly 1> stdout.txt
lilypond file.ly 2> stderr.txt
lilypond file.ly &> all.txt

find . -name '*.ly' -exec lilypond '{}' \;

forfiles /s /M *.ly /c "cmd /c lilypond @file"

forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c lilypond @file"

forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c lilypond @file"

command key=value

set? FONTCONFIG_FILE=$INSTALLER_PREFIX/etc/fonts/fonts.conf
prependdir GUILE_LOAD_PATH=$INSTALLER_PREFIX/share/guile/1.8

#!/bin/sh
## defaults set here

username=lily
home=/home
loopdevice=/dev/loop0
jaildir=/mnt/lilyloop
# the prefix (without the leading slash!)
lilyprefix=usr/local
# the directory where lilypond is installed on the system
lilydir=/$lilyprefix/lilypond/

userhome=$home/$username
loopfile=$userhome/loopfile
adduser $username
dd if=/dev/zero of=$loopfile bs=1k count=200000
mkdir $jaildir
losetup $loopdevice $loopfile
mkfs -t ext3 $loopdevice 200000
mount -t ext3 $loopdevice $jaildir
mkdir $jaildir/lilyhome
chown $username $jaildir/lilyhome
cd $jaildir

mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts $lilyprefix tmp
chmod a+w tmp

cp -r -L $lilydir $lilyprefix
cp -L /bin/sh /bin/rm bin
cp -L /usr/bin/convert /usr/bin/gs usr/bin
cp -L /usr/share/fonts/truetype usr/share/fonts

# Now the library copying magic
for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh"  \
  "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=>  \
    \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed  \
      's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/'  \
        | sed '/.*=>.*/d'; done | sh -s

# The shared files for Ghostscript...
      cp -L -r /usr/share/ghostscript usr/share
# The shared files for ImageMagick
      cp -L -r /usr/lib/ImageMagick* usr/lib

### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome,
### you should be able to run:
### Note that /$lilyprefix/bin/lilypond is a script, which sets the
### LD_LIBRARY_PATH - this is crucial
      /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly

1.3 Error messages

Different error messages can appear while compiling a file:

Warning ¶

Something looks suspect. If you are requesting something out of the ordinary then you will understand the message, and can ignore it. However, warnings usually indicate that something is wrong with the input file.

Error ¶

Something is definitely wrong. The current processing step (parsing, interpreting, or formatting) will be finished, but the next step will be skipped.

Fatal error ¶

Something is definitely wrong, and LilyPond cannot continue. This happens rarely. The most usual cause is misinstalled fonts.

Scheme error ¶

Errors that occur while executing Scheme code are caught by the Scheme interpreter. If running with the verbose option (-V or --verbose) then a call trace of the offending function call is printed.

Programming error ¶

There was some internal inconsistency. These error messages are intended to help the programmers and debuggers. Usually, they can be ignored. Sometimes, they come in such big quantities that they obscure other output.

Aborted (core dumped) ¶

This signals a serious programming error that caused the program to crash. Such errors are considered critical. If you stumble on one, send a bug-report.

If warnings and errors can be linked to some part of the input file, then error messages have the following form

filename:lineno:columnno: message
offending input line

A line-break is inserted in the offending line to indicate the column where the error was found. For example,

test.ly:2:19: error: not a duration: 5
  { c'4 e'
           5 g' }

These locations are LilyPond’s best guess about where the warning or error occurred, but (by their very nature) warnings and errors occur when something unexpected happens. If you can’t see an error in the indicated line of your input file, try checking one or two lines above the indicated position.

Please note that diagnostics can be triggered at any point during the many stages of processing. For example if there are parts of the input that are processed multiple times (i.e., in midi and layout output), or if the same music variable is used in multiple contexts the same message may appear several times. Diagnostics produced at a ‘late’ stage (i.e., bar checks) might also be issued multiple times.

See Common errors for more information about errors.

1.4 Common errors

The error conditions described below occur often, yet the cause is not obvious or easily found. Once seen and understood, they are easily handled.

\override VerticalAxisGroup.staff-affinity = ##f

\score {
  % Invalid! Generates error: syntax error, unexpected \new
  \new Staff { … }
  \new Staff { … }
}

2.1 Why does the syntax change?

Syntax changes are often made to make the LilyPond input code simpler for both reading and writing, but occasionally changes are made to accommodate new features or enhancements to existing functions.

Here is a real example to illustrate this.

All \paper and \layout property names are supposed to be written in the form first-second-third. However, in LilyPond version 2.11.60, it was noticed that the printallheaders property did not follow this convention. Should this property be left alone (confusing new users with an inconsistent format)? Or should it be changed (annoying old users with existing LilyPond input files)? The decision was eventually made to change the name of the property to print-all-headers, and by using the convert-ly command old users had a way to automatically update their existing input files.

Unfortunately, the convert-ly command is not capable to manage all syntax changes. For example, accents and non-English characters were entered using standard LaTeX notation in versions of LilyPond before 2.6; words like ‘Noël’ (which is ‘Christmas’ in French) had to be entered as No\"el. Starting with LilyPond 2.6, the special letter ‘ë’ must be entered directly as a UTF-8 character. Because convert-ly cannot convert LaTeX special characters into UTF-8 characters, older LilyPond input files have to be edited manually to take care of that.

The conversion rules of the convert-ly command work by using text pattern matching and replacement (rather than ‘understanding’ the context of what it is changing within a given input file). This has several consequences:

• The reliability of the conversion depends on the quality of each applied rule set and on the complexity of the respective change. Sometimes conversions may require additional, manual fixes, so the original input files should be kept for comparison just in case.
• Only conversions to newer syntax changes are possible: there are no rule sets to go back to older versions of LilyPond. As a consequence, input files should only be upgraded when older versions of LilyPond are no longer being maintained. Again, the original data should be kept just in case, perhaps by using version control systems like Git to help maintain multiple versions of your input files.
• LilyPond is quite robust when processing ‘creatively’ placed or omitted whitespace, but the rules used by convert-ly often make some stylistic assumptions. For painless upgrades it is therefore advised to follow the input style as used in the LilyPond manuals, particularly as the examples in the manuals themselves are all upgraded using the convert-ly command.

2.2 Command-line preliminaries

This and the following sections only cover the command-line usage of convert-ly. GUI applications like Frescobaldi have their own interfaces to convert-ly.

By ‘command line’, we mean the command line in the operating system. Windows users might be more familiar with the terms ‘DOS shell’ or ‘command shell’. macOS users might be more familiar with the terms ‘terminal’ or ‘console’.

Describing how to use this part of an operating system is outside the scope of this manual; please consult other documentation on this topic if you are unfamiliar with the command line.

See The PATH environment variable how to set up the operating system so that convert-ly can be used on the command line without specifying a path.

Additional setup for Windows

[Non-Windows users can skip this section; Windows users who have a Python interpreter already installed (version 3.8 or higher) can skip this section, too.]

convert-ly is actually a Python script called convert-ly.py. In the LilyPond binary bundle for Windows it is located in the same directory as the lilypond.exe binary and a Python interpreter, python.exe. Assuming that you have unpacked version 2.25.22 within a directory C:\Users\me and PATH is correctly set up, it would be still necessary to say

python C:\Users\me\lilypond-2.25.22\bin\convert-ly.py myfile.ly

which is tedious to type.

Three steps are necessary to allow the omission of both the interpreter (python.exe) and the .py extension.³

1. On the command line, say

   assoc .py=PythonScript
   

   to associate the extension .py with the file type ‘PythonScript’.

2. As the next command, say

   ftype PythonScript=C:\Users\me\lilypond-2.25.22\bin\python.exe %1 %*
   

   to make files of type ‘PythonScript’ be handled by LilyPond’s python.exe. You have to adjust the path to the actual location, and don’t omit the trailing ‘%1 %*’!

3. Modify the PATHEXT environment variable and add .py to already present entries. Do this in exactly the same way as you have already done with PATH.

Now close the command line and open it again, then test whether convert-ly --version works.

2.3 Invoking convert-ly

The convert-ly command uses the \version number in the input file to detect older versions. In most cases it is sufficient just to run

convert-ly -e myfile.ly

in the directory containing the input file; this upgrades myfile.ly in-place and preserves the original file by renaming it to myfile.ly~. The \version number in the upgraded input file, along with any required syntax updates, is also changed.

When run, the convert-ly command outputs the version numbers of which conversions have been made to. If no version numbers are listed in the output for the file, it is already up to date and using the latest LilyPond syntax.

To convert all input files in a single directory, use

convert-ly -e *.ly

as a command. To handle all input files that reside in different subdirectories, try

find . -name '*.ly' -exec convert-ly -e '{}' \;

to recursively search and convert them in the current directory and all directories below it. The converted files will be located in the same directory along with their renamed originals.

On Windows, execute

forfiles /s /M *.ly /c "cmd /c convert-ly -e @file"

instead. The forfiles command also accepts an explicit path to the top level of your folder containing all the sub-folders that have input files in them by using the /p option.

forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c convert-ly -e @file"

If there are spaces in the path to the top-level folder, the whole path needs to be inside double quotes, for example

forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c convert-ly -e @file"

2.4 Command-line options for convert-ly

The program is invoked as follows:

convert-ly [option]… filename…

By default, convert-ly writes its data to standard output.

The following options can be given:

--version

Show version number and exit.

-h, --help

Show usage help and exit.

-d, --diff-version-update

Increase the \version string only if the file has actually been changed. In that case, the version header will correspond to the version after the last actual change. An unstable version number will be rounded up to the next stable version number unless that would exceed the target version number. Without this option, the version will instead reflect the last attempted conversion.

-e, --edit

Apply the conversions directly to the input file, modifying it in-place. If the original file is called myfile.ly, a backup is retained under the name myfile.ly~, i.e., a tilde character gets appended. This backup file may be a hidden file on some operating systems.

If you want the converted output to be stored under a different name, redirect the standard output to a file.

convert-ly myfile.ly > mynewfile.ly

See also option --backup-numbered.

-b, --backup-numbered

When used with the ‘-e’ option, number the backup files so that no previous version is overwritten. Assuming the input file is called myfile.ly, try to store the backup in myfile.ly.~1~. If it exists, try myfile.ly.~2~ instead, etc. The backup files may be hidden on some operating systems.

-f, --from=from-patchlevel

Set the version to convert from. If this is not set, convert-ly will guess it on the basis of the (first) \version string in the file. Example: --from=2.10.25

-h, --help

Print usage help.

-l loglevel, --loglevel=loglevel

Set the output verbosity to loglevel. Possible values, in upper case, are PROGRESS (the default), NONE, WARN, ERROR, and DEBUG.

-n, --no-version

Normally, convert-ly adds a \version indicator to the output. Specifying this option suppresses this.

-c, --current-version

By default, convert-ly updates the \version string to the lowest necessary version. If this option is given, the current LilyPond version (2.25.22) is used instead.

-s, --show-rules

Show conversion descriptions and exit. The amount of information can be adjusted with options --from and --to.

-t, --to=to-patchlevel

Explicitly set which \version to convert to, otherwise the default is the most current value. It must be higher than the starting version.

convert-ly --to=2.14.1 myfile.ly

-v, --verbose

Display rule descriptions during conversion.

-w, --warranty

Show warranty and copyright and exit.

To upgrade LilyPond fragments in Texinfo files, use

convert-ly --from=… --to=… --no-version *.itely

To see the changes in the LilyPond syntax between two versions, use

convert-ly --from=… --to=… -s

2.5 Problems running convert-ly

If an input (or output) file name contains spaces it is necessary to surround the file name with double quotes.

convert-ly "D:/My Scores/Ode.ly" > "D:/My Scores/new Ode.ly"

If the invocation of convert-ly -e *.ly fails because the expanded command line becomes too long, the convert-ly command may be placed in a loop instead. This example for UNIX upgrades all .ly files in the current directory

for f in *.ly; do convert-ly -e $f; done

For Windows, the corresponding command is

for %x in (*.ly) do convert-ly.py -e "%x"

in the command prompt window.

As discussed earlier, not all language changes are handled. In particular, automatically updating Scheme and LilyPond Scheme interfaces is quite unlikely; be prepared to tweak Scheme code manually.

2.6 Manual conversions

In theory, a program like convert-ly could handle any syntax change. After all, a computer program interprets the old version and the new version, so another computer program can translate one file into another.⁴

However, the LilyPond project has limited resources: not all conversions are performed automatically. If convert-ly is not able to handle a syntax change, it emits a warnings like the following (from the 2.23.12 conversion rule).

Not smart enough to convert music following \fine.

Warning: \fine no longer enforces the end of the music.
If your piece has music following \fine that you want to
exclude when it is unfolded, use \volta to exclude it.
Please refer to the manual for details, and update manually.

2.7 Writing code to support multiple versions

In some cases, especially when writing library code it is desirable to support multiple LilyPond versions across breaking syntax changes. To do this alternative portions of code can be wrapped into conditional expressions depending on the currently executed LilyPond version. The Scheme function ly:version? expects a comparison operator op and a reference version ver passed as a list of integers with up to three elements. Missing elements are ignored so '(2 20) is equivalent to any version of the 2.20 line of versions. Constructs like the following are possible:

#(cond
  ((ly:version? > '(2 20))
   (ly:message "This is code to run for LilyPond after 2.20"))
  ((ly:version? = '(2 19 57))
   (ly:message "This will only be executed with LilyPond 2.19.57"))
  (else (ly:message "This will be executed in any other version")))

Usually this will be integrated in library functions to allow alternative syntax to be used, but it is also possible to use the comparison directly within the music like in the following example:

{
  c' d' e' f'
  #(if (ly:version? = '(2 21))
       #{ \override NoteHead.color = #red #}
       #{ \override NoteHead.color = #blue #})
  g' a' b' c''
}

Note: This function has been introduced in LilyPond 2.21.80, so it is not possible to compare with versions earlier than that.

3.1 An example of a musicological document

Some texts contain music examples. These texts are musicological treatises, songbooks, or manuals like this. Such texts can be made by hand, simply by importing a PostScript or PDF figure into the word processor. However, there is an automated procedure to reduce the amount of work involved in HTML, LaTeX, Texinfo and DocBook documents.

A script called lilypond-book will extract the music fragments, format them, and put back the resulting notation. Here we show a small example for use with LaTeX. The example also contains explanatory text, so we will not comment on it further.

Input

\documentclass[a4paper]{article}

\begin{document}

Documents for \verb+lilypond-book+ may freely mix music and text.
For example,

\begin{lilypond}
\relative {
  c'2 e2 \tuplet 3/2 { f8 a b } a2 e4
}
\end{lilypond}

Options are put in brackets.

\begin{lilypond}[fragment,quote,staffsize=26,verbatim]
  c'4 f16
\end{lilypond}

Larger examples can be put into a separate file, and introduced with
\verb+\lilypondfile+.

\lilypondfile[quote,noindent]{screech-and-boink.ly}

(If needed, replace @file{screech-and-boink.ly} by any @file{.ly} file
you put in the same directory as this file.)

\end{document}

Processing

Save the code above to a file called lilybook.lytex, then in a terminal run

lilypond-book --output=out --pdf lilybook.lytex
lilypond-book (GNU LilyPond) 2.25.22 
Reading lilybook.lytex...
…lots of stuff deleted…
Compiling lilybook.tex...
cd out
pdflatex lilybook
…lots of stuff deleted…
xpdf lilybook
(replace xpdf by your favorite PDF viewer)

Running lilypond-book and latex creates a lot of temporary files, which would clutter up the working directory. To remedy this, use the --output=dir option. It will create the files in a separate subdirectory dir.

Finally the result of the LaTeX example shown above.⁵ This finishes the tutorial section.

Output

Documents for lilypond-book may freely mix music and text. Using Texinfo syntax, this example

@lilypond
\relative {
  c'2 e2 \tuplet 3/2 { f8 a b } a2 e4
}
@end lilypond

produces

Options to control the appearance of snippets can be added, too. Using LaTeX syntax, this example

\begin{lilypond}[fragment, quote, staffsize=26]
c'4 f16
\end{lilypond}

produces

Larger music snippets can be put into separate files. Using HTML syntax, this example

<lilypondfile quote noindent>
  snippets/screech-and-boink.ly
</lilypondfile>

produces

If a tagline is required, either default or custom, the entire snippet must be enclosed in a \book { } construct.

\book {
  \header { title = "A scale in LilyPond" }

  \relative { c' d e f g a b c }
}

3.2 Integrating music and text

Here we explain in detail how to integrate LilyPond with various output formats.

\begin{lilypond}[options,go,here]
  YOUR LILYPOND CODE
\end{lilypond}

\lilypond[options,go,here]{ YOUR LILYPOND CODE }

\lilypondfile[options,go,here]{filename}

\musicxmlfile[options,go,here]{filename}

\begin{lilypond}[quote,fragment,staffsize=26]
  c'4 d' e' f' g'2 g'
\end{lilypond}

\lilypond[quote,fragment,staffsize=11]{<c' e' g'>}

\def\betweenLilyPondSystem#1{\endinput}

\begin{lilypond}[fragment]
  c'1\( e'( c'~ \break c' d) e f\)
\end{lilypond}

\def\betweenLilyPondSystem#1{
  \ifnum#1<2\else\expandafter\endinput\fi
}

\let\betweenLilyPondSystem\undefined

\def\onlyFirstNSystems#1{
  \def\betweenLilyPondSystem##1{%
    \ifnum##1<#1\else\expandafter\endinput\fi}
}

\onlyFirstNSystems{3}
\begin{lilypond}…\end{lilypond}
\onlyFirstNSystems{1}
\begin{lilypond}…\end{lilypond}

@lilypond[options,go,here]
  YOUR LILYPOND CODE
@end lilypond

@lilypond[options,go,here]{ YOUR LILYPOND CODE }

@lilypondfile[options,go,here]{filename}

@musicxmlfile[options,go,here]{filename}

@lilypond[quote,fragment]
  c'4 d' e' f' g'2 g'
@end lilypond

@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}

<lilypond options go here>
  YOUR LILYPOND CODE
</lilypond>

<lilypond options go here: YOUR LILYPOND CODE />

<lilypondfile options go here>filename</lilypondfile>

<musicxmlfile options go here>filename</musicxmlfile>

<lilypond quote fragment staffsize=26>
  c'4 d' e' f' g'2 g'
</lilypond>

<lilypond quote fragment staffsize=11: <c' e' g'> />

<mediaobject>
  <imageobject>
    <imagedata fileref="music1.ly"
               role="printfilename" />
  </imageobject>
</mediaobject>

<inlinemediaobject>
  <textobject>
    <programlisting language="lilypond"
                    role="fragment verbatim staffsize=16
                          ragged-right relative=2">
\context Staff \with {
  \remove Time_signature_engraver
  \remove Clef_engraver}
  { c4( fis) }
    </programlisting>
  </textobject>
</inlinemediaobject>

3.3 Music fragment options

In the following, a ‘lilypond-book command’ refers to any command described in the previous sections that is handled by lilypond-book to produce a music snippet. For simplicity, lilypond-book commands are only shown in Texinfo syntax (i.e., starting with ‘@’) to make them better distinguishable from LilyPond commands.

Note that the option string is parsed from left to right; if an option occurs multiple times, the last one is taken.

The following options are available for lilypond-book commands:

staffsize=ht

Set staff size to ht, which is measured in points.

ragged-right

Produce ragged-right lines with natural spacing, i.e., ragged-right = ##t is added to the LilyPond snippet. Single-line snippets will always be typeset by default as ragged-right, unless noragged-right is explicitly given.

noragged-right

For single-line snippets, allow the staff length to be stretched to equal that of the line width, i.e., ragged-right = ##f is added to the LilyPond snippet.

line-width

line-width=size\unit

Set line width to size (expressed in unit). unit is one of the following: cm, mm, in, pt, or bp. This option affects LilyPond output (that is, the staff length of the music fragment), not the text layout.

If used without an argument, or if no line-width option is given, lilypond-book tries to guess a default for lilypond environments that don’t use the ragged-right option.

See also option papersize.

papersize=string

Set paper size to string (for example a5 or letter) for music fragments that use \book. See Predefined paper sizes for a list of available paper sizes.

This option affects LilyPond output (that is, the paper size of the music fragment), not the text layout. Unknown values of string are ignored: a warning is emitted and the snippet is printed using the document’s paper size for LaTeX and Texinfo, and the A4 paper format for HTML and DocBook.

If option papersize is given without option line-width (more specifically, option line-width without an argument), LilyPond uses its own idea of the default line width within the snippet, also ignoring option quote (which still makes lilypond-book emit a quotation block, though).

paper-width=size\unit

Set paper width to size (expressed in unit) for music fragments that use \book. unit is one of the following: cm, mm, in, pt, or bp.

This option affects LilyPond output (that is, the paper width of the music fragment), not the text layout. If set, it overrides option papersize if given. If option paper-height is not specified, the paper height is set to the document’s paper height for LaTeX and Texinfo, and the A4 paper height (296mm) for HTML and DocBook.

paper-height=size\unit

Set paper height to size (expressed in unit) for music fragments that use \book. unit is one of the following: cm, mm, in, pt, or bp.

This option affects LilyPond output (that is, the paper height of the music fragment), not the text layout. If set, it overrides option papersize if given. If option paper-width is not specified, the paper width is set to the document’s paper width for LaTeX and Texinfo, and the A4 paper width (210mm) for HTML and DocBook.

Example:

\lilypond[paper-width=10\cm, paper-height=57\mm]{
  \book {
    ...
  }
}

notime

Do not print the time signature and turn off the timing (time signature, bar lines) in the score.

fragment

Make lilypond-book add some boilerplate code so that you can simply enter, say,

c'4

without \layout, \score, etc.

nofragment

Do not add additional code to complete LilyPond code in music snippets. Since this is the default, nofragment is redundant normally.

inline

inline=vshift

Set up snippet for inline use, that is, to be typeset within a paragraph. The snippet itself is formatted with a very small left padding (approximately the same as the right padding), ignoring the value given by the command-line option --left-padding.

For the LaTeX backend, the inline image gets shifted vertically; vshift is a factor of the current image’s height. If no argument is given a default value of -0.3 is used, thus moving the image down by approx. one third of its height. The default value can be adjusted with command-line option --inline-vshift.

For Texinfo output, it suppresses the insertion of a blank line before and after the snippet. For HTML output, it suppresses the insertion of <p> before and </p> after the snippet.

To actually make a snippet appear inline in LaTeX and Texinfo mode, it is necessary to position it within a paragraph, avoiding an empty line before and after the snippet. For example, this LaTeX code

The motive
\lilypond[inline,staffsize=11]{
  { \time 2/4 r8 g'[ g' g'] | es'2 }
}
is widely known.

becomes

The motive is widely known.

indent=size\unit

Set indentation of the first music system to size (expressed in unit). unit is one of the following: cm, mm, in, pt, or bp. This option affects LilyPond, not the text layout.

noindent

Set indentation of the first music system to zero. This option affects LilyPond, not the text layout. Since no indentation is the default, noindent is redundant normally.

quote

Reduce line length of a music snippet by 2*0.4in and put the output into a quotation block. The value ‘0.4in’ can be controlled with the exampleindent option.

See also option papersize.

exampleindent

Set the amount by which the quote option indents a music snippet.

relative

relative=n

Use relative octave mode. By default, notes are specified relative to middle C. The optional integer argument specifies the octave of the starting note, where the default 1 is middle C. relative option only works when fragment option is set, so fragment is automatically implied by relative, regardless of the presence of any (no)fragment option in the source.

LilyPond also uses lilypond-book to produce its own documentation. To do that, some more obscure music fragment options are available.

verbatim

The argument of a lilypond-book command is copied to the output file and enclosed in a verbatim block, followed by any text given with the intertext option (not implemented yet); then the actual music is displayed. This option does not work well with @lilypond{} if it is part of a paragraph.

If verbatim is used in a lilypondfile command, it is possible to enclose verbatim only a part of the source file. If the source file contain a comment containing ‘begin verbatim’ (without quotes), quoting the source in the verbatim block will start after the last occurrence of such a comment; similarly, quoting the source verbatim will stop just before the first occurrence of a comment containing ‘end verbatim’, if there is any. In the following source file example, the music will be interpreted in relative mode, but the verbatim quote will not show the relative block, i.e.,

\relative { % begin verbatim
  c'4 e2 g4
  f2 e % end verbatim
}

will be printed with a verbatim block like

  c4 e2 g4
  f2 e

If you would like to translate comments and variable names in verbatim output but not in the sources, you may set the environment variable LYDOC_LOCALEDIR to a directory path; the directory should contain a tree of .mo message catalogs with lilypond-doc as a domain.

texidoc

(Only for Texinfo output, and only for @lilypondfile.) If lilypond is called with the --header=texidoc option, and the file to be processed is called foo.ly, it creates a file foo.texidoc if there is a texidoc field in the \header block of foo.ly. lilypond-book’s texidoc option makes it include such a file, adding its contents as a documentation block right before the music snippet (but outside the example environment generated by a quote option).

Assuming the file foo.ly contains

\header {
  texidoc = "This file demonstrates a single note."
}
{ c'4 }

and we have this in our Texinfo document test.texinfo

@lilypondfile[texidoc]{foo.ly}

the following command line gives the expected result

lilypond-book --pdf \
              --process="lilypond --header=texidoc" \
              test.texinfo

All LilyPond documentation snippets (in the Documentation/snippets directory of the distribution) are .ly files that have such texidoc fields in their \header blocks.

For localization purposes, if the Texinfo document contains @documentlanguage XX and foo.ly’s \header block contains a texidocXX field, and if lilypond is called with --header=texidocXX, then foo.texidocXX gets included instead of foo.texidoc, if present. XX is usually a two-letter string like ‘de’ (for German) or ‘ca’ (for Catalan).

doctitle

(Only for Texinfo output, and only for @lilypondfile.) This option works similarly to the texidoc option: if lilypond is called with the --header=doctitle option, and the file to be processed is called foo.ly and contains a doctitle field in the \header block, it creates a file foo.doctitle. When the doctitle option is used, the contents of foo.doctitle, which should be a single line of text, is inserted in the Texinfo document as @lydoctitle text. @lydoctitle should be a macro defined in the Texinfo document. The same remark about texidoc processing with localized documentation also applies to doctitle.

nogettext

(Only for Texinfo output.) Do not translate comments and variable names in the snippet quoted verbatim.

printfilename

If a LilyPond input file is included with lilypondfile command, print the file name right before the music snippet. For HTML output, this is a link. Only the base name of the file is printed, i.e., the directory part of the file path is stripped.

3.4 Invoking lilypond-book

lilypond-book produces a file with one of the following extensions: .tex, .texi, .html or .xml, depending on the output format. All of .tex, .texi and .xml files need further processing.

Format-specific instructions

LaTeX

There are two ways of processing your LaTeX document for printing or publishing: getting a PDF file directly with pdfLaTeX (XeLaTeX, luaLaTeX) or getting a PostScript file with LaTeX via a DVI-to-PostScript translator like dvips. The first way is simpler and recommended⁷, and whichever way you use, you can easily convert between PostScript and PDF with tools, like ps2pdf and pdf2ps included in Ghostscript package.

To produce a PDF file with pdfLaTeX, use:

lilypond-book --pdf yourfile.lytex
pdflatex yourfile.tex

To produce PDF output via LaTeX/dvips/ps2pdf:

lilypond-book yourfile.lytex
latex yourfile.tex
dvips -Ppdf yourfile.dvi
ps2pdf yourfile.ps

The .dvi file created by this process will not contain note heads. This is normal; if you follow the instructions, they will be included in the .ps and .pdf files.

Running dvips may produce some warnings about fonts; these are harmless and may be ignored. If you are running latex in twocolumn mode, remember to add -t landscape to the dvips options.

Environments such as

\begin{lilypond} … \end{lilypond}

are not interpreted by LaTeX. Instead, lilypond-book extracts those ‘environments’ into files of its own and runs LilyPond on them. It then takes the resulting graphics and creates a .tex file where the \begin{lilypond}…\end{lilypond} macros are replaced by ‘graphics inclusion’ commands. It is at this time that LaTeX is run (although LaTeX will have run previously, it will have been, effectively, on an ‘empty’ document in order to calculate paper dimensions and the line width for LilyPond snippets).

Known issues and warnings

The \pageBreak command will not work within a \begin{lilypond} … \end{lilypond} environment.

Many \paper block variables will also not work within a \begin{lilypond} … \end{lilypond} environment. Use \newcommand with \betweenLilyPondSystem in the preamble.

\newcommand{\betweenLilyPondSystem}[1]{\vspace{36mm}\linebreak}

Texinfo

To produce a Texinfo document (in any output format), follow the normal procedures for Texinfo; that is, either call texi2pdf or texi2dvi or texi2any, depending on the output format you want to create. By default, texi2pdf uses pdftex for processing, which you can verify in the console output. In this case, run lilypond-book with the --pdf option so that it creates .pdf snippets instead of .eps files. pdftex is unable to include the latter ones and will output an error message otherwise.

See the documentation of Texinfo for further details.

Command-line options

lilypond-book accepts the following command-line options.

-f format

--format=format

Specify the document type to process: html, latex, texi (the default), texi-html, or docbook. If this option is missing, lilypond-book tries to detect the format automatically, see Filename extensions. Currently, texi-html is the same as texi.

-F filter

--filter=filter

Pipe snippets through filter. With this option, lilypond-book does not create snippet files; instead, it modifies the code of the embedded snippets in the input document and emits the resulting file, which in turn can then be processed by another run with lilypond-book (without the --filter option). Example:

lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely

lilypond-book does not accept options --filter and --process at the same time.

-h

--help

Print a short help message.

-I dir

--include=dir

Add dir to the include path. Since lilypond-book also looks for already compiled snippets in the include path and does not write them back to the output directory, it is necessary in some cases to invoke further processing commands such as texi2any or latex with the same -I dir options.

-l loglevel

--loglevel=loglevel

Set the output verbosity to loglevel. Possible values are NONE, ERROR, WARN, PROGRESS (default), and DEBUG. If this option is not used and the environment variable LILYPOND_BOOK_LOGLEVEL is set, its value is used as the log level.

-o dir

--output=dir

Place generated files into directory dir. Running lilypond-book generates lots of small files that LilyPond will process. To avoid all that clutter in the source directory, use the --output command-line option, and change to that directory before running latex or texi2any.

lilypond-book --output=out yourfile.lytex
cd out
…

--skip-lily-check

Do not fail if no LilyPond output is found. It is used for generating LilyPond’s Info documentation without images.

--skip-png-check

Do not fail if no PNG images are found for EPS files. It is used for generating LilyPond’s Info documentation without images.

--lily-output-dir=dir

Write lily-XXX files to directory dir and link into --output directory. Use this option to save building time for documents in different directories that share a lot of identical snippets.

--lily-loglevel=loglevel

Set the output verbosity of the invoked lilypond command to loglevel. Possible values are NONE, ERROR, WARN, BASIC, PROGRESS, INFO (default), and DEBUG. If this option is not used and the environment variable LILYPOND_LOGLEVEL is set, its value is used as the log level.

--info-images-dir=dir

Format Texinfo output so that Info will look for images of music in directory dir.

--inline-vshift=vshift

In the LaTeX backend, use vshift to vertically move all inline images. vshift is a factor of an image’s height; the default value is -0.3, thus moving the images down by approx. one third of their individual heights. The factor can be locally overridden with an argument to the inline snippet option.

--latex-program=prog

Run executable prog instead of latex. This is useful if your document is processed with xelatex, for example.

--left-padding=amount

Pad LilyPond snippets on the left with whitespace.

amount is given in millimeters relative to the start of the staff. The default value is 3.0mm.

The widths of tightly clipped systems can vary due to notation elements such as bar numbers or instrument names that are positioned left of the beginning of staves. The padding sets the minimum distance between the left margin of the snippet images and the beginning of (non-indented) staves; this allows the expected vertical alignment of snippets in the master document.

In addition to padding at the left, this option shortens each staff line by amount. As a consequence, each line is moved to the right visually.

Note that amount, as used for padding, is rounded up to be an integer multiple of the big point (bp) unit for PostScript and PDF output (one bp is 1/72th of an inch, approx. 0.353mm). However, this is not done on the LilyPond side for shortening the staff line. This might lead to a tiny but probably surprising staff length change instead of changing the padding if amount is not an integer multiple of the bp unit.

-P command

--process=command

Process LilyPond snippets using command. The default command is lilypond. lilypond-book does not accept options --filter and --process at the same time.

--pdf

Create PDF snippet files. If not set, only PNG and EPS files are produced. Use this option if you want to directly embed PDF files into LaTeX or Texinfo files.

--redirect-lilypond-output

By default, logging output is displayed on the terminal. This option redirects all output to log files in the same directory as the source files.

--use-source-file-names

Write snippet output files with the same base name as their source file. This option works only for snippets included with the lilypondfile command and only if directories implied by --output-dir and --lily-output-dir options are different.

-V

--verbose

Be verbose. This is equivalent to --loglevel=DEBUG.

-v

--version

Print version information.

Known issues and warnings

The Texinfo command @pagesizes is not interpreted. Similarly, LaTeX commands that change margins and line widths after the preamble are ignored.

Only the first \score of a LilyPond block is processed.

3.5 Filename extensions

You can use any file name extension for the input file, but if you do not use the recommended extension for a particular format you may need to manually specify the output format; for details, see Invoking lilypond-book. Otherwise, lilypond-book automatically selects the output format based on the input file name’s extension.

extension	output format
.html	HTML
.htmly	HTML
.itely	Texinfo
.latex	LaTeX
.lytex	LaTeX
.lyxml	DocBook
.tely	Texinfo
.tex	LaTeX
.texi	Texinfo
.texinfo	Texinfo
.xml	HTML

If you use the same file name extension for the input file than the extension lilypond-book uses for the output file, and if the input file is in the same directory as lilypond-book working directory, you must use --output option to make lilypond-book running, otherwise it will exit with an error message like “Output would overwrite input file”.

3.6 Parallel execution

The lilypond-book script cannot be used to process documents in parallel if the output directory is the same. If you try to do so, sequential execution (in arbitrary order) of the lilypond-book processes is enforced instead by using a lock file.

In other words, to process documents foo.lytex and bar.lytex at the same time (via the make utility, for example), put them either into two different directories, say, foo/foo.lytex and bar/bar.lytex, or use command-line option --output with different values.

Note that LilyPond itself can process multiple input files in parallel, actually. Since lilypond-book passes a list of all snippets in a document to lilypond in one rush, parallel execution is possible by using its -djob-count option.

lilypond-book --process="lilypond -djob-count=4" \
              --output=foo \
              ... \
              foo.lytex

3.7 lilypond-book templates

These templates are for use with lilypond-book. If you’re not familiar with this program, please refer to Running lilypond-book.

LaTeX

You can include LilyPond fragments in a LaTeX document.

\documentclass{article}

% here you can insert packages all LaTeX flavours understand
\usepackage[ngerman,finnish,english]{babel}
\usepackage{graphicx}
\usepackage{libertinus}

\usepackage{iftex}
\ifxetex
  % stuff specific to XeTeX
  \usepackage{xltxtra}
\else
  % this can be empty if you are not going to use pdfTeX
  \usepackage[T1]{fontenc}
\fi


\begin{document}

\title{A short document with LilyPond and \LaTeX}
\maketitle

Normal \textbf{font} commands inside the \emph{text} work,
because they are \textsf{supported by all \LaTeX{} flavours}.
If you want to use specific commands like \verb+\XeTeX+, you
should include them again in a \verb+\ifxetex+ block.
You can use this to print the \ifxetex \XeTeX{} \else XeTeX \fi
command, which is not known to pdfTeX by default.

In normal text you can easily use LilyPond commands, like this:

\smallskip
\begin[staffsize=12]{lilypond}
{ a2^"foo" b_"bar" c'8 c' c' c' }

\paper {
  property-defaults.fonts.serif = "Libertinus Serif"
}
\end{lilypond}
\smallskip

\noindent
Note that the fonts used in snippets have to be set from inside
the snippets, as demonstrated.

\selectlanguage{ngerman}
Da die Standard-Eingabekodierung von \LaTeX{} UTF-8 ist,
funktionieren Umlaute u.\,ä. ohne \LaTeX-Akzentbefehle (ßäöü),
wenn sie von der Schriftart unterstützt werden.

\end{document}

Texinfo

You can include LilyPond fragments in Texinfo; in fact, this entire manual is written in Texinfo.

\input texinfo 
@ifnottex
@node Top
@top
@end ifnottex

Texinfo text

@lilypond
\relative {
  a4 b c d
}
@end lilypond

More Texinfo text, and options in brackets.

@lilypond[verbatim,fragment,ragged-right]
d4 c b a
@end lilypond

@bye

HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<body>

<p>
Documents for lilypond-book may freely mix music and text.  For
example,
<lilypond>
\relative {
  a'4 b c d
}
</lilypond>
</p>

<p>
Another bit of lilypond, this time with options:

<lilypond fragment quote staffsize=26 verbatim>
a4 b c d
</lilypond>
</p>

</body>
</html>

3.8 Sharing the table of contents

These functions already exist in the OrchestralLily package:

https://repo.or.cz/w/orchestrallily.git

For greater flexibility in text handling, some users prefer to export the table of contents from lilypond and read it into LaTeX.

Exporting the ToC from LilyPond

This assumes that your score has multiple movements in the same lilypond output file.

#(define (oly:create-toc-file layout pages)
  (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
    (if (not (null? label-table))
      (let* ((format-line (lambda (toc-item)
             (let* ((label (car toc-item))
                    (text  (caddr toc-item))
                    (label-page (and (list? label-table)
                                     (assoc label label-table)))
                    (page (and label-page (cdr label-page))))
               (format #f "~a, section, 1, {~a}, ~a" page text label))))
             (formatted-toc-items (map format-line (toc-items)))
             (whole-string (string-join formatted-toc-items ",\n"))
             (output-name (ly:parser-output-name))
             (outfilename (format #f "~a.toc" output-name))
             (outfile (open-output-file outfilename)))
        (if (output-port? outfile)
            (display whole-string outfile)
            (ly:warning (G_ "Unable to open output file ~a for the TOC information") outfilename))
        (close-output-port outfile)))))

\paper {
  #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
}

Importing the ToC into LaTeX

In LaTeX, the header should include:

\usepackage{pdfpages}
\includescore{nameofthescore}

where \includescore is defined as:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \includescore{PossibleExtension}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Read in the TOC entries for a PDF file from the corresponding .toc file.
% This requires some heave latex tweaking, since reading in things from a file
% and inserting it into the arguments of a macro is not (easily) possible

% Solution by Patrick Fimml on #latex on April 18, 2009:
% \readfile{filename}{\variable}
% reads in the contents of the file into \variable (undefined if file
% doesn't exist)
\newread\readfile@f
\def\readfile@line#1{%
{\catcode`\^^M=10\global\read\readfile@f to \readfile@tmp}%
\edef\do{\noexpand\g@addto@macro{\noexpand#1}{\readfile@tmp}}\do%
\ifeof\readfile@f\else%
\readfile@line{#1}%
\fi%
}
\def\readfile#1#2{%
\openin\readfile@f=#1 %
\ifeof\readfile@f%
\typeout{No TOC file #1 available!}%
\else%
\gdef#2{}%
\readfile@line{#2}%
\fi
\closein\readfile@f%
}%


\newcommand{\includescore}[1]{
\def\oly@fname{\oly@basename\@ifmtarg{#1}{}{_#1}}
\let\oly@addtotoc\undefined
\readfile{\oly@xxxxxxxxx}{\oly@addtotoc}
\ifx\oly@addtotoc\undefined
\includepdf[pages=-]{\oly@fname}
\else
\edef\includeit{\noexpand\includepdf[pages=-,addtotoc={\oly@addtotoc}]
{\oly@fname}}\includeit
\fi
}

3.9 Alternative methods of mixing text and music

Other means of mixing text and music (without lilypond-book) are discussed in LilyPond output in other programs.

4.1 Point and click

Point and click lets you find notes in the input by clicking on them in the PDF viewer. This makes it easier to find input that causes some error in the sheet music.

export LYEDITOR=atom

atom %(file)s:%(line)s:%(column)s

export LYEDITOR="code --goto %(file)s:%(line)s:%(column)s"

[Desktop Entry]
Version=1.0
Name=lilypond-invoke-editor
GenericName=Textedit URI handler
Comment=URI handler for textedit:
Exec=lilypond-invoke-editor %u
Terminal=false
Type=Application
MimeType=x-scheme-handler/textedit;
Categories=Editor
NoDisplay=true

xdg-desktop-menu install ./lilypond-invoke-editor.desktop
xdg-mime default lilypond-invoke-editor.desktop x-scheme-handler/textedit

xdg-open textedit:///etc/issue:1:0:0

# For Textedit links
/usr/local/bin/lilypond-invoke-editor Cx -> sanitized_helper,

sudo apparmor_parser -r -T -W /etc/apparmor.d/usr.bin.evince

\pointAndClickOff

\pointAndClickOn

lilypond -dno-point-and-click file.ly

4.2 Text editor support

There is support for different text editors for LilyPond.

(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))

filetype off
set runtimepath+=/usr/local/share/lilypond/current/vim/
filetype on
syntax on

4.3 Converting from other formats

Music can be entered also by importing it from other formats. This chapter documents the tools included in the distribution to do so. There are other tools that produce LilyPond input, for example GUI sequencers and XML converters. Refer to the website for more details.

These are separate programs from lilypond itself, and are run on the command line; see Command-line usage for more information.

Known issues and warnings

We unfortunately do not have the resources to maintain these programs; please consider them “as-is”. Patches are appreciated, but bug reports will almost certainly not be resolved.

midi2ly [option]… midi-file

musicxml2ly [option]… file.xml

abc2ly [option]… abc-file

%%LY voices \set autoBeaming = ##f

%%LY slyrics more words

etf2ly [option]… etf-file

4.4 LilyPond output in other programs

This section shows methods to integrate text and music, different than the automated method with lilypond-book.

lilypond -dseparate-page-formats=pdf myfile.ly

lilypond -dtall-page-formats=png myfile.ly

lilypond -dseparate-page-formats=eps,pdf -dtall-page-formats=png,svg myfile.ly

\paper{
  indent=0\mm
  oddFooterMarkup=##f
  oddHeaderMarkup=##f
  bookTitleMarkup = ##f
  scoreTitleMarkup = ##f
}

… music …

4.5 Independent includes

Some users have produced files that can be \included with LilyPond to produce certain effects and those listed below are part of the LilyPond distribution. Also see Working with input files.

5.1 General suggestions

Here are a few suggestions that can help to avoid (and fix) the most common problems when typesetting:

• Always include a \version number in your input files no matter how small they are. This prevents having to remember which version of LilyPond the file was created with and is especially relevant when Updating files with convert-ly command (which requires the \version statement to be present); or if sending your input files to other users (e.g., when asking for help on the mail lists). Note that all of the LilyPond templates contain \version numbers.
• For each line in your input file, write one bar of music. This will make debugging any problems in your input files much simpler.
• Include bar checks, bar number checks, as well as octave checks (see Bar and bar number checks and Octave checks). Including ‘checks’ of this type in your input files will help pinpoint mistakes more quickly. How often checks are added will depend on the complexity of the music being typeset. For simple compositions, checks added at a few at strategic points within the music can be enough but for more complex music, with many voices and/or staves, checks may be better placed after every bar.
• Add comments within input files. References to musical themes (i.e. ‘second theme in violins’, ‘fourth variation,’ etc.), or simply including bar numbers as comments, will make navigating the input file much simpler especically if something needs to be altered later on or if passing on LilyPond input files to another person.
• Add explicit note durations at the start of ‘sections’. For example, c4 d e f instead of just c d e f can make rearranging the music later on simpler.
• Learn to indent and align braces and parallel music. Many problems are often caused by either ‘missing’ braces. Clearly indenting ‘opening’ and ‘closing’ braces (or << and >> indicators) will help avoid such problems. For example;

  \new Staff {
    \relative {
      r4 g'8 g c8 c4 d |
      e4 r8 |
      % Ossia section
      <<
        { f8 c c | }
        \new Staff {
          f8 f c |
        }
      >>
      r4 |
    }
  }
  

  is much easier to follow than;

  \new Staff { \relative { r4 g'8 g c4 c8 d | e4 r8
  % Ossia section
  << { f8 c c } \new Staff { f8 f c } >> r4 | } }
  

• Keep music and style separate by putting overrides in the \layout block;

  \score {
    …music…
    \layout {
     \override TabStaff.Stemstencil = ##f
   }
  }
  

  This will not create a new context but it will apply when one is created. Also see Saving typing with variables and functions, and Style sheets.

5.2 Typesetting existing music

If you are entering music from an existing score (i.e., typesetting a piece of existing sheet music),

• Enter the manuscript (the physical copy of the music) into LilyPond one system at a time (but still only one bar per line of text), and check each system when you finish it. You may use the showLastLength or showFirstLength properties to speed up processing – see Skipping corrected music.
• Define mBreak = { \break } and insert \mBreak in the input file whenever the manuscript has a line break. This makes it much easier to compare the LilyPond music to the original music. When you are finished proofreading your score, you may define mBreak = { } to remove all those line breaks. This will allow LilyPond to place line breaks wherever it feels are best.
• When entering a part for a transposing instrument into a variable, it is recommended that the notes are wrapped in

  \transpose c natural-pitch {…}
  

  (where natural-pitch is the open pitch of the instrument) so that the music in the variable is effectively in C. You can transpose it back again when the variable is used, if required, but you might not want to (e.g., when printing a score in concert pitch, converting a trombone part from treble to bass clef, etc.). Mistakes in transpositions are less likely if all the music in variables is at a consistent pitch.

  Also, only ever transpose to/from C. That means that the only other keys you will use are the natural pitches of the instruments - bes for a B-flat trumpet, aes for an A-flat clarinet, etc.

5.3 Large projects

When working on a large project, having a clear structure to your lilypond input files becomes vital.

• Use a variable for each voice, with a minimum of structure inside the definition. The structure of the \score section is the most likely thing to change; the violin definition is extremely unlikely to change in a new version of LilyPond.

  violin = \relative {
  g'4 c'8. e16
  }
  …
  \score {
    \new GrandStaff {
      \new Staff {
        \violin
      }
    }
  }
  

• Separate tweaks from music definitions. This point was made previously, but for large projects it is absolutely vital. We might need to change the definition of fthenp, but then we only need to do this once, and we can still avoid touching anything inside violin.

  fthenp = _\markup{
    \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
  violin = \relative {
  g'4\fthenp c'8. e16
  }
  

5.4 Troubleshooting

Sooner or later, you will write a file that LilyPond cannot compile. The messages that LilyPond gives may help you find the error, but in many cases you need to do some investigation to determine the source of the problem.

The most powerful tools for this purpose are the single line comment (indicated by %) and the block comment (indicated by %{…%}). If you don’t know where a problem is, start commenting out huge portions of your input file. After you comment out a section, try compiling the file again. If it works, then the problem must exist in the portion you just commented. If it doesn’t work, then keep on commenting out material until you have something that works.

In an extreme case, you might end up with only

\score {
  <<
    % \melody
    % \harmony
    % \bass
  >>
  \layout{}
}

(in other words, a file without any music)

If that happens, don’t give up. Uncomment a bit – say, the bass part – and see if it works. If it doesn’t work, then comment out all of the bass music (but leave \bass in the \score uncommented.

bass = \relative {
%{
  c'4 c c c
  d d d d
%}
}

Now start slowly uncommenting more and more of the bass part until you find the problem line.

Another very useful debugging technique is constructing Tiny examples.

5.5 Make and Makefiles

Pretty well all the platforms LilyPond can run on support a software facility called make. This software reads a special file called a Makefile that defines what files depend on what others and what commands you need to give the operating system to produce one file from another. For example the makefile would spell out how to produce ballad.pdf and ballad.midi from ballad.ly by running LilyPond.

There are times when it is a good idea to create a Makefile for your project, either for your own convenience or as a courtesy to others who might have access to your source files. This is true for very large projects with many included files and different output options (e.g., full score, parts, conductor’s score, piano reduction, etc.), or for projects that require difficult commands to build them (such as lilypond-book projects). Makefiles vary greatly in complexity and flexibility, according to the needs and skills of the authors. The program GNU Make comes installed on GNU/Linux distributions and on macOS, and it is also available for Windows.

See the GNU Make Manual for full details on using make, as what follows here gives only a glimpse of what it can do.

The commands to define rules in a makefile differ according to platform; for instance the various forms of GNU/Linux and macOS use bash, while Windows uses cmd. Note that on macOS, you need to configure the system to use the command-line interpreter. Here are some example makefiles, with versions for both GNU/Linux/macOS and Windows.

The first example is for an orchestral work in four movements with a directory structure as follows:

Symphony/
|-- MIDI/
|-- Makefile
|-- Notes/
|   |-- cello.ily
|   |-- figures.ily
|   |-- horn.ily
|   |-- oboe.ily
|   |-- trioString.ily
|   |-- viola.ily
|   |-- violinOne.ily
|   `-- violinTwo.ily
|-- PDF/
|-- Parts/
|   |-- symphony-cello.ly
|   |-- symphony-horn.ly
|   |-- symphony-oboe.ly
|   |-- symphony-viola.ly
|   |-- symphony-violinOne.ly
|   `-- symphony-violinTwo.ly
|-- Scores/
|   |-- symphony.ly
|   |-- symphonyI.ly
|   |-- symphonyII.ly
|   |-- symphonyIII.ly
|   `-- symphonyIV.ly
`-- symphonyDefs.ily

The .ly files in the Scores and Parts directories get their notes from .ily files in the Notes directory:

%%% top of file "symphony-cello.ly"
\include "../symphonyDefs.ily"
\include "../Notes/cello.ily"

The makefile will have targets of score (entire piece in full score), movements (individual movements in full score), and parts (individual parts for performers). There is also a target archive that will create a tarball of the source files, suitable for sharing via web or email. Here is the makefile for GNU/Linux or macOS. It should be saved with the name Makefile in the top directory of the project:

# the name stem of the output files
piece := symphony
# The command to run lilypond
LILY_CMD := lilypond -ddelete-intermediate-files \
                    -dno-point-and-click

# The suffixes used in this Makefile.
.SUFFIXES: .ly .ily .pdf .midi

.DEFAULT_GOAL := score

PDFDIR := PDF
MIDIDIR := MIDI

# Input and output files are searched in the directories listed in
# the VPATH variable.  All of them are subdirectories of the current
# directory (given by the GNU make variable `CURDIR`).
VPATH := \
  $(CURDIR)/Scores \
  $(CURDIR)/Parts \
  $(CURDIR)/Notes \
  $(CURDIR)/$(PDFDIR) \
  $(CURDIR)/$(MIDIDIR)

# The pattern rule to create PDF and MIDI files from a LY input file.
# The .pdf output files are put into the `PDF` subdirectory, and the
# .midi files go into the `MIDI` subdirectory.
%.pdf %.midi: %.ly | $(PDFDIR) $(MIDIDIR)
	$(LILY_CMD) $<          	# this line begins with a tab
	mv "$*.pdf" $(PDFDIR)/		# this line begins with a tab
	mv "$*.midi" $(MIDIDIR)/	# this line begins with a tab

$(PDFDIR):
	mkdir $(PDFDIR)

$(MIDIDIR):
	mkdir $(MIDIDIR)

common := symphonyDefs.ily

notes := \
  cello.ily \
  horn.ily \
  oboe.ily \
  viola.ily \
  violinOne.ily \
  violinTwo.ily

# The dependencies of the movements.
$(piece)I.pdf: $(piece)I.ly $(notes) $(common)
$(piece)II.pdf: $(piece)II.ly $(notes) $(common)
$(piece)III.pdf: $(piece)III.ly $(notes) $(common)
$(piece)IV.pdf: $(piece)IV.ly $(notes) $(common)

# The dependencies of the full score.
$(piece).pdf: $(piece).ly $(notes) $(common)

# The dependencies of the parts.
$(piece)-cello.pdf: $(piece)-cello.ly cello.ily $(common)
$(piece)-horn.pdf: $(piece)-horn.ly horn.ily $(common)
$(piece)-oboe.pdf: $(piece)-oboe.ly oboe.ily $(common)
$(piece)-viola.pdf: $(piece)-viola.ly viola.ily $(common)
$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily $(common)
$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily $(common)

# Type `make score` to generate the full score of all four
# movements as one file.
.PHONY: score
score: $(piece).pdf

# Type `make parts` to generate all parts.
# Type `make symphony-foo.pdf` to generate the part for instrument 'foo'.
# Example: `make symphony-cello.pdf`.
.PHONY: parts
parts: $(piece)-cello.pdf \
       $(piece)-violinOne.pdf \
       $(piece)-violinTwo.pdf \
       $(piece)-viola.pdf \
       $(piece)-oboe.pdf \
       $(piece)-horn.pdf

# Type `make movements` to generate files for the
# four movements separately.
.PHONY: movements
movements: $(piece)I.pdf \
           $(piece)II.pdf \
           $(piece)III.pdf \
           $(piece)IV.pdf

all: score parts movements

There are special complications on the Windows platform. After downloading and installing GNU Make for Windows, you must set the correct path in the system’s environment variables so that the DOS shell can find the Make program. To do this, right-click on "My Computer," then choose Properties and Advanced. Click Environment Variables, and then in the System Variables pane, highlight Path, click edit, and add the path to the GNU Make executable file, which will look something like this:

C:\Program Files\GnuWin32\bin

The makefile itself has to be altered to handle different shell commands and to deal with spaces that are present in some default system directories. Windows also has a different default extension for midi files.

## WINDOWS VERSION
##
piece := symphony
LILY_CMD := lilypond -ddelete-intermediate-files \
                    -dno-point-and-click

#get the 8.3 name of CURDIR (workaround for spaces in PATH)
workdir := $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
          do @echo %%~sb)

.SUFFIXES: .ly .ily .pdf .mid

.DEFAULT_GOAL := score

PDFDIR := PDF
MIDIDIR := MIDI

VPATH := \
  $(workdir)/Scores \
  $(workdir)/Parts \
  $(workdir)/Notes \
  $(workdir)/$(PDFDIR) \
  $(workdir)/$(MIDIDIR)

%.pdf %.mid: %.ly | $(PDFDIR) $(MIDIDIR)
        $(LILY_CMD) $<			# this line begins with a tab
        move /Y "$*.pdf"  $(PDFDIR)/	# begin with tab
        move /Y "$*.mid" $(MIDIDIR)/	# begin with tab

$(PDFDIR):
    mkdir $(PDFDIR)/

$(MIDIDIR):
    mkdir $(MIDIDIR)/

notes := \
  cello.ily \
  figures.ily \
  horn.ily \
  oboe.ily \
  trioString.ily \
  viola.ily \
  violinOne.ily \
  violinTwo.ily

common := symphonyDefs.ily

$(piece)I.pdf: $(piece)I.ly $(notes) $(common)
$(piece)II.pdf: $(piece)II.ly $(notes) $(common)
$(piece)III.pdf: $(piece)III.ly $(notes) $(common)
$(piece)IV.pdf: $(piece)IV.ly $(notes) $(common)

$(piece).pdf: $(piece).ly $(notes) $(common)

$(piece)-cello.pdf: $(piece)-cello.ly cello.ily $(common)
$(piece)-horn.pdf: $(piece)-horn.ly horn.ily $(common)
$(piece)-oboe.pdf: $(piece)-oboe.ly oboe.ily $(common)
$(piece)-viola.pdf: $(piece)-viola.ly viola.ily $(common)
$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily $(common)
$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily $(common)

.PHONY: score
score: $(piece).pdf

.PHONY: parts
parts: $(piece)-cello.pdf \
       $(piece)-violinOne.pdf \
       $(piece)-violinTwo.pdf \
       $(piece)-viola.pdf \
       $(piece)-oboe.pdf \
       $(piece)-horn.pdf

.PHONY: movements
movements: $(piece)I.pdf \
           $(piece)II.pdf \
           $(piece)III.pdf \
           $(piece)IV.pdf

all: score parts movements

The next Makefile is for a lilypond-book document done in LaTeX. This project has an index, which requires that the latex command be run twice to update links. Output files are all stored in the out directory for .pdf output and in the htmlout directory for the html output.

SHELL=/bin/sh
FILE=myproject
OUTDIR=out
WEBDIR=htmlout
VIEWER=acroread
BROWSER=firefox
LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
PDF=cd $(OUTDIR) && pdflatex $(FILE)
HTML=cd $(WEBDIR) && latex2html $(FILE)
INDEX=cd $(OUTDIR) && makeindex $(FILE)
PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &

all: pdf web keep

pdf:
        $(LILYBOOK_PDF)  # begin with tab
        $(PDF)           # begin with tab
        $(INDEX)         # begin with tab
        $(PDF)           # begin with tab
        $(PREVIEW)       # begin with tab

web:
        $(LILYBOOK_HTML) # begin with tab
        $(HTML)          # begin with tab
        cp -R $(WEBDIR)/$(FILE)/ ./  # begin with tab
        $(BROWSER) $(FILE)/$(FILE).html &  # begin with tab

keep: pdf
        cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf  # begin with tab

clean:
        rm -rf $(OUTDIR) # begin with tab

web-clean:
        rm -rf $(WEBDIR) # begin with tab

archive:
        tar -cvvf myproject.tar \ # begin this line with tab
        --exclude=out/* \
        --exclude=htmlout/* \
        --exclude=myproject/* \
        --exclude=*midi \
        --exclude=*pdf \
        --exclude=*~ \
        ../MyProject/*

TODO: make this thing work on Windows

The previous makefile does not work on Windows. An alternative for Windows users would be to create a simple batch file containing the build commands. This will not keep track of dependencies the way a makefile does, but it at least reduces the build process to a single command. Save the following code as build.bat or build.cmd. The batch file can be run at the DOS prompt or by simply double-clicking its icon.

lilypond-book --output=out --pdf myproject.lytex
cd out
pdflatex myproject
makeindex myproject
pdflatex myproject
cd ..
copy out\myproject.pdf MyProject.pdf

See also

This manual: Command-line usage, Running lilypond-book.