3.2 Integrating music and text

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

3.2.1 LaTeX

LaTeX is the de-facto standard for publishing layouts in the exact sciences. It is built on top of the TeX typesetting engine, providing the best typography available anywhere.

See The Not So Short Introduction to LaTeX for an overview on how to use LaTeX.

lilypond-book provides the following commands and environments to include music in LaTeX files:

• the \lilypond{…} command, where you can directly enter short lilypond code
• the \begin{lilypond}…\end{lilypond} environment, where you can directly enter longer lilypond code
• the \lilypondfile{…} command to insert a lilypond file
• the \musicxmlfile{…} command to insert a MusicXML file, which will be processed by musicxml2ly and lilypond.

In the input file, music is specified with any of the following commands:

\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}

Additionally, \lilypondversion displays the current version of lilypond. Running lilypond-book yields a file that can be further processed with LaTeX.

We show some examples here. The lilypond environment

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

produces

The short version

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

produces

Currently, you cannot include { or } within \lilypond{}, so this command is only useful with the fragment option.

The default line width of the music will be adjusted by examining the commands in the document preamble, the part of the document before \begin{document}. The lilypond-book command sends these to LaTeX to find out how wide the text is. The line width for the music fragments is then adjusted to the text width. Note that this heuristic algorithm can fail easily; in such cases it is necessary to use the line-width music fragment option.

Each snippet will call the following macros if they have been defined by the user:

• \preLilyPondExample called before the music,
• \postLilyPondExample called after the music,
• \betweenLilyPondSystem[1] is called between systems if lilypond-book has split the snippet into several PostScript files. It must be defined as taking one parameter and will be passed the number of files already included in this snippet. The default is to simply insert a \linebreak.

Selected Snippets

Sometimes it is useful to display music elements (such as ties and slurs) as if they continued after the end of the fragment. This can be done by breaking the staff and suppressing inclusion of the rest of the LilyPond output.

In LaTeX, define \betweenLilyPondSystem in such a way that inclusion of other systems is terminated once the required number of systems are included. Since \betweenLilyPondSystem is first called after the first system, including only the first system is trivial.

\def\betweenLilyPondSystem#1{\endinput}

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

If a greater number of systems is requested, a TeX conditional must be used before the \endinput. In this example, replace ‘2’ by the number of systems you want in the output.

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

(Since \endinput immediately stops the processing of the current input file we need \expandafter to delay the call of \endinput after executing \fi so that the \if-\fi clause is balanced.)

Remember that the definition of \betweenLilyPondSystem is effective until TeX quits the current group (such as the LaTeX environment) or is overridden by another definition (which is, in most cases, for the rest of the document). To reset your definition, write

\let\betweenLilyPondSystem\undefined

in your LaTeX source.

This may be simplified by defining a TeX macro

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

and then saying only how many systems you want before each fragment,

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

See also

There are specific lilypond-book command line options and other details to know when processing LaTeX documents, see Invoking lilypond-book.

3.2.2 Texinfo

Texinfo is the standard format for documentation of the GNU project. An example of a Texinfo document is this manual. The HTML, PDF, and Info versions of the manual are made from the Texinfo document.

lilypond-book provides the following commands and environments to include music into Texinfo files:

• the @lilypond{…} command, where you can directly enter short lilypond code
• the @lilypond…@end lilypond environment, where you can directly enter longer lilypond code
• the @lilypondfile{…} command to insert a lilypond file
• the @musicxmlfile{…} command to insert a MusicXML file, which will be processed by musicxml2ly and lilypond.

In the input file, music is specified with any of the following commands

@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}

Additionally, @lilypondversion displays the current version of lilypond.

When lilypond-book is run on it, this results in a Texinfo file (with extension ‘.texi’) containing @image tags for HTML, Info and printed output. lilypond-book generates images of the music in EPS and PDF formats for use in the printed output, and in PNG format for use in HTML and Info output.

We show two simple examples here. A lilypond environment

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

produces

The short version

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

produces

Contrary to LaTeX, @lilypond{…} does not generate an in-line image. It always gets a paragraph of its own.

3.2.3 HTML

lilypond-book provides the following commands and environments to include music in HTML files:

• the <lilypond … /> command, where you can directly enter short lilypond code
• the <lilyond>…</lilypond> environment, where you can directly enter longer lilypond code
• the <lilypondfile>…</lilypondfile> command to insert a lilypond file
• the <musicxmlfile>…</musicxmlfile> command to insert a MusicXML file, which will be processed by musicxml2ly and lilypond.

In the input file, music is specified with any of the following commands:

<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>

For example, you can write

<lilypond fragment relative=2>
\key c \minor c4 es g2
</lilypond>

lilypond-book then produces an HTML file with appropriate image tags for the music fragments:

For inline pictures, use <lilypond … />, where the options are separated by a colon from the music, for example

Some music in <lilypond relative=2: a b c/> a line of text.

To include separate files, say

<lilypondfile option1 option2 …>filename</lilypondfile>

<musicxmlfile> uses the same syntax as <lilypondfile>, but simply references a MusicXML file rather than a LilyPond file.

For a list of options to use with the lilypond or lilypondfile tags, see Music fragment options.

Additionally, <lilypondversion/> displays the current version of lilypond.

3.2.4 DocBook

For inserting LilyPond snippets it is good to keep the conformity of our DocBook document, thus allowing us to use DocBook editors, validation etc. So we don’t use custom tags, only specify a convention based on the standard DocBook elements.

Common conventions

For inserting all type of snippets we use the mediaobject and inlinemediaobject element, so our snippets can be formatted inline or not inline. The snippet formatting options are always provided in the role property of the innermost element (see in next sections). Tags are chosen to allow DocBook editors format the content gracefully. The DocBook files to be processed with lilypond-book should have the extension ‘.lyxml’.

Including a LilyPond file

This is the most simple case. We must use the ‘.ly’ extension for the included file, and insert it as a standard imageobject, with the following structure:

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

Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.

Including LilyPond code

Including LilyPond code is possible by using a programlisting, where the language is set to lilypond with the following structure:

<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>

As you can see, the outermost element is a mediaobject or inlinemediaobject, and there is a textobject containing the programlisting inside.

Processing the DocBook document

Running lilypond-book on our ‘.lyxml’ file will create a valid DocBook document to be further processed with ‘.xml’ extension. If you use dblatex, it will create a PDF file from this document automatically. For HTML (HTML Help, JavaHelp etc.) generation you can use the official DocBook XSL stylesheets, however, it is possible that you have to make some customization for it.

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.