GNU LilyPond

Welcome to the home of the GNU Music Typesetter

Node:lilypond-book, Next:Internals, Previous:Conversion tools, Up:Top

lilypond-book

lilypond-book runs Lilypond on fragments of lilypond in a LaTeX or texinfo file, and includes the results into a document that can be processed with LaTeX, makeinfo or texi2dvi. The result is a text document containing formatted music integrated.

More precisely, if a LaTeX file contains

        \begin{lilypond}
        CONTENTS
        \end{lilypond}

        \lilypond{CONTENTS}

Very often, if you mix music and text, the music is only a few notes or at most a few bars. This music should be as short as possible and not stretched to be aligned to the right margin. lilypond-book does this automatically if you don't use a \score block in CONTENTS. For example: \lilypond{\context Voice <c' e' g'> }.

You can also use lilypondfile to include another file:

        \lilypondfile{foo.ly}

All three forms can take several options. They are specified in brackets as follows:

       \lilypondfile[options, go, here]{ ..  }
       \begin[options, go, here]{lilypond} .. \end{lilypond}
       \lilypond[options, go,here]{ .. }

In the texinfo version, bitmaps of the music are also generated, so you can make a HTML document with embedded music.

TeXinfo reference

You specify the lilypond code like this:

@lilypond[options, go, here]
 YOUR LILYPOND CODE
@end lilypond
@lilypond[option, go, here]{ YOUR LILYPOND CODE }
@lilypondfile[options, go,here]{filename}

lilypond-book knows the default margins, and a few paper sizes. One of these commands should be in the beginning of the document:

• @afourpaper
• @afourlatex
• @afourwide
• @smallbook

Examples

Two simple examples. First a complete block:

@lilypond[26pt]
c' d' e' f' g'2 g'
@end lilypond

produces this music:

Then the short version:

@lilypond[11pt]{<c' e' g'>}

and its music:

LaTeX reference

You specify the lilypond code like this:

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

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

\lilypond{ YOUR LILYPOND CODE }

Lilypond-book know about the \onecolumn and \twocolumn commands, the geometry package and all the standard paper sizes.

The music will be surrounded by \preLilypondExample and \postLilypondExample. The variables are defined to nothing by default, and the user can redefine them to whatever he wants.

Examples

\begin[26pt]{lilypond}
c' d' e' f' g'2 g'2
\end{lilypond}

produces this music:

Then the short version:

\lilypond[11pt]{<c' e' g'>}

and its music:

Options

eps

This will create the music as eps graphics and include it into the document with the \includegraphics command. It works in LaTeX only.

This enables you to place music examples in the running text (and not in a separate paragraph). To avoid that LaTeX places the music on a line of its own, there should be no empty lines between the normal text and the lilypond environment. For inline music, you probably also need a smaller music font size (eg. 11 pt or 13 pt)

verbatim

CONTENTS is copied into the source enclosed in a verbatim block, followed by any text given with the intertext option, then the actual music is displayed. This option does not work with the short version of the lilypond blocks:

@lilypond{ CONTENTS } and \lilypond{ CONTENTS }

intertext="text"

Used in conjunction with verbatim option: this puts text between the code and the music.

filename=FILENAME

Save the lilypond code to FILENAME. By default, a hash value of the code is used.

11pt

13pt

16pt

20pt

26pt

singleline

Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).

multiline

The opposite of singleline: justify and break lines.

fragment

nofragment

Override lilypond-book auto detection of what type of code is in the lilypond block, voice contents or complete code.

printfilename

Prints the file name before the music example. Useful in conjunction with \lilypondfile.

relative, relative N

Use relative octave mode. By default, notes are specified relative central C. The optional integer argument specifies how many octaves higher (positive number) or lower (negative number) to place the starting note.

Invocation

When you run lilypond-book it will generate lots of small files that Lilypond will process. So to avoid all the garbage in your source directory, you should either change to a temporary directory, or use the --outdir command line options:

cd out && lilypond-book ../yourfile.tex

lilypond-book --outdir=out yourfile.tex

For latex input, the file to give to latex has extension .latex. TeXinfo input will be written to a file with extension .texi.

If you use --outdir, you should also cd to that directory before running LaTeX or makeinfo. This may seem a little kludgey, but both Latex and makeinfo expect picture files (the music) to be in the current working directory. Moreover, if you do this, LaTeX will not clutter you normal working directory with output files.

If you want to add titling from the \header section of the files, you should add the following to the top of your LaTeX

\input titledefs.tex
\def\preLilypondExample{\def\mustmakelilypondtitle{}}

Command line options

-f, --format=

Specify the document type to process, latex or texi. lilypond-book usually figure this out automatically.

--default-music-fontsize=szpt

Set the fontsize to use for lilypond if no fontsize is given as option.

--force-music-fontsize=szpt

Force all lilypond to use this fontsize, overriding options given to \begin{lilypond}

-I DIR, --include=DIR

Add DIR to the include path.

-M, --dependencies

Write dependencies to filename.dep

--dep-prefix=PREF

prepend PREF before each -M dependency

-n, --no-lily

don't run lilypond, but do generate the .ly files

--no-pictures

don't generate pictures when processing texinfo.

--read-lys

don't write ly files. This way you can do

 lilypond-book file.tely
 convert-ly
 lilypond-book --read-lys

[TODO not a useful option unless you can undump the input file]

--outname=FILE

The name of LaTeX file to output. If this option is not given, the output name is derived from the input name.

--outdir=DIR

place generated files in DIR.

--version

print version information

--help

Print a short help message

lilypond-book is written in python 1.5, so you have to install python.

Bugs

The LaTeX \includeonly{...} command is ignored.

The TeXinfo command pagesize is on the TODO list for Lilypond 1.4, but changing the linewidth in other ways will not give you a straight right margin.

Almost all LaTeX commands that change margins and line widths are ignored.

Since there is no finder's fee which doubles every year, there is no need to wait for the prize money to grow. So send a bug report today if you need this one of these options.

Authors

Please send GNU LilyPond questions and comments to lilypond-user@gnu.org.

Please send comments on these web pages to lilypond@packages.debian.org

Copyright (c) 1997--2001 Han-Wen Nienhuys and Jan Nieuwenhuizen.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.