<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- header_tag -->
<html lang="en">
<head>
<title>Introduction to the LilyPond file structure - GNU LilyPond Learning Manual</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="GNU LilyPond Learning Manual">
<meta name="generator" content="makeinfo 4.11">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="How-LilyPond-input-files-work.html#How-LilyPond-input-files-work" title="How LilyPond input files work">
<link rel="next" href="Score-is-a-_0028single_0029-compound-musical-expression.html#Score-is-a-_0028single_0029-compound-musical-expression" title="Score is a (single) compound musical expression">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1999--2007 by the authors
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections. A copy of the license is
included in the section entitled ``GNU Free Documentation
License''.
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
hr { border:0; height:1; color: #000000; background-color: #000000; }
/* hr {
border: none;
height: 1px;
color: #666666;
background-color: #666666;
}
body {
border-left: 1px solid #666666;
border-right: 1px solid #666666;
color: #332d28;
margin-right: auto;
margin-left: auto;
width: 60em;
list-style-type: square;
font-family: Arial,Helvetica,sans-serif;
padding-right: 1em;
padding-left: 1em;
}
a {
border-bottom: 1px dashed #344242;
text-decoration: none;
color: #344242;
}
a:link {
text-decoration: none;
}
a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
a:active {
border-bottom: 1px solid #00cccc;
color: #00cccc;
}
a:hover {
border-bottom: 1px solid #1d7b85;
color: #1d7b85;
}
blockquote {
border: 1px solid #cccccc;
padding: 3px;
width: 40em;
}
.node {
border-left: 1px solid #666666;
margin: -0.5em 0px 1em;
padding: 2px 1px 0px;
font-style: italic;
}
.node a {
border: none;
text-decoration: underline;
font-style: normal;
font-weight: bold;
}
.verbatim {
font-family: "Courier New",Courier,monospace;
}
.unnumberedsubsubsec {
font-size: large;
color: #1d7b85;
}
.subsubheading {
font-size: large;
color: #3b220d;
}
.contents {
border: 1px dashed #339999;
margin: 3px 2em;
list-style-type: square;
padding-right: 1em;
width: 40em;
background-color: #fcfff9;
}
.contents a {
border-bottom: 1px dashed #423d34;
text-decoration: none;
color: #423d34;
}
.contents a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
.contents a:active {
border-bottom: 1px solid #f0d86d;
color: #f0d86d;
}
.contents a:hover {
border-bottom: 1px solid #3b220d;
color: #3b220d;
}
.menu {
border-left: 1px dashed #339999;
margin: 3px 2em 1em;
list-style-type: square;
padding-left: 1.4em;
width: 40em;
}
.unnumbered {
}
h2 {
font-size: x-large;
color: #1d7b85;
}
*/
--></style>
</head>
<BODY BGCOLOR=WHITE TEXT=BLACK>
<div class="node">
<p>
<a name="Introduction-to-the-LilyPond-file-structure"></a>
Next: <a rel="next" accesskey="n" href="Score-is-a-_0028single_0029-compound-musical-expression.html#Score-is-a-_0028single_0029-compound-musical-expression">Score is a (single) compound musical expression</a>,
Up: <a rel="up" accesskey="u" href="How-LilyPond-input-files-work.html#How-LilyPond-input-files-work">How LilyPond input files work</a>
<hr>
</div>
<h4 class="subsection">3.1.1 Introduction to the LilyPond file structure</h4>
<p><a name="index-input-format-173"></a><a name="index-file-structure-174"></a>
A basic example of a LilyPond input file is
<pre class="example">\version "2.11.57"<!-- /@w -->
\header { }
\score {
<var>...compound music expression...</var> % all the music goes here!
\layout { }
\midi { }
}
</pre>
<p class="noindent">There are many variations of this basic pattern, but this
example serves as a useful starting place.
<p><a name="index-g_t_005cbook-175"></a><a name="index-g_t_005cbook-176"></a>
<a name="index-g_t_005cscore-177"></a><a name="index-g_t_005cscore-178"></a>
<a name="index-book-179"></a><a name="index-score-180"></a>
Up to this point none of the examples you have seen has used a
<code>\score{}</code> command. This is because LilyPond automatically
adds the extra commands which are needed when you give it simple
input. LilyPond treats input like this:
<pre class="example">\relative c'' {
c4 a d c
}
</pre>
<p class="noindent">as shorthand for this:
<pre class="example">\book {
\score {
\new Staff {
\new Voice {
\relative c'' {
c4 a b c
}
}
}
\layout { }
}
}
</pre>
<p>In other words, if the input contains a single music expression,
LilyPond will interpret the file as though the music expression
was wrapped up inside the commands shown above.
<p><a name="index-implicit-contexts-181"></a>
<strong>A word of warning!</strong> Many of the examples in the LilyPond
documentation will omit the <code>\new Staff</code> and <code>\new Voice</code>
commands, leaving them to be created implicitly. For simple
examples this works well, but for more complex examples, especially
when additional commands are used, the implicit creation of contexts
can give surprising results, maybe creating extra unwanted staves.
The way to create contexts explicitly is explained in
<a href="Contexts-and-engravers.html#Contexts-and-engravers">Contexts and engravers</a>.
<p><table class="cartouche" summary="cartouche" border="1"><tr><td>
<b>Note:</b> When entering more than a few lines of music it is
advisable to always create staves and voices explicitly.
</td></tr></table>
<p>For now, though, let us return to the first example and examine the
<code>\score</code> command, leaving the others to default.
<p>A <code>\score</code> block must always contain just one music expression,
and this must appear immediately after the <code>\score</code> command.
Remember that a music expression could be anything from a single
note to a huge compound expression like
<pre class="example">{
\new GrandStaff <<
<var>...insert the whole score of a Wagner opera in here...</var>
>>
}
</pre>
<p class="noindent">Since everything is inside <code>{ ... }</code>, it counts
as one music expression.
<p>As we saw previously, the <code>\score</code> block can contain other
things, such as
<pre class="example">\score {
{ c'4 a b c' }
\header { }
\layout { }
\midi { }
}
</pre>
<p><a name="index-g_t_005cheader-182"></a><a name="index-g_t_005cheader-183"></a>
<a name="index-g_t_005clayout-184"></a><a name="index-g_t_005clayout-185"></a>
<a name="index-g_t_005cmidi-186"></a><a name="index-g_t_005cmidi-187"></a>
<a name="index-header-188"></a><a name="index-layout-189"></a><a name="index-midi-190"></a>
Note that these three commands – <code>\header</code>, <code>\layout</code> and
<code>\midi</code> – are special: unlike many other commands which begin
with a backward slash (<code>\</code>) they are <em>not</em> music expressions
and are not part of any music expression. So they may be placed
inside a <code>\score</code> block or outside it. In fact, these commands
are commonly placed outside the <code>\score</code> block – for example,
<code>\header</code> is often placed above the <code>\score</code> command, as the
example at the beginning of this section shows.
<p>Two more commands you have not previously seen are
<code>\layout { }</code> and <code>\midi {}</code>. If these appear as
shown they will cause LilyPond to produce a printed output and a
MIDI output respectively. They are described fully in the
Notation Reference – <a name="index-Score-layout-191"></a><a href="../lilypond/Score-layout.html#Score-layout">Score layout</a>, and
<a name="index-Creating-MIDI-files-192"></a><a href="../lilypond/Creating-MIDI-files.html#Creating-MIDI-files">Creating MIDI files</a>.
<p><a name="index-scores_002c-multiple-193"></a>
You may code multiple <code>\score</code> blocks. Each will be
treated as a separate score, but they will be all combined into
a single output file. A <code>\book</code> command is not necessary
– one will be implicitly created. However, if you would like
separate output files from one <code>.ly</code> file then the
<code>\book</code> command should be used to separate the different
sections: each <code>\book</code> block will produce a
separate output file.
<p>In summary:
<p>Every <code>\book</code> block creates a separate output file (e.g., a
PDF file). If you haven't explicitly added one, LilyPond wraps
your entire input code in a <code>\book</code> block implicitly.
<p>Every <code>\score</code> block is a separate chunk of music within a
<code>\book</code> block.
<p>Every <code>\layout</code> block affects the <code>\score</code> or
<code>\book</code> block in which it appears – i.e., a <code>\layout</code>
block inside a <code>\score</code> block affects only that <code>\score</code>
block, but a <code>\layout</code> block outside of a <code>\score</code> block
(and thus in a <code>\book</code> block, either explicitly or
implicitly) will affect every <code>\score</code> in that <code>\book</code>.
<p>For details see <a name="index-Multiple-scores-in-a-book-194"></a><a href="../lilypond/Multiple-scores-in-a-book.html#Multiple-scores-in-a-book">Multiple scores in a book</a>.
<p><a name="index-variables-195"></a>
Another great shorthand is the ability to define variables. All
the templates use this
<pre class="example">melody = \relative c' {
c4 a b c
}
\score {
\melody
}
</pre>
<p>When LilyPond looks at this file, it takes the value of
<code>melody</code> (everything after the equals sign) and inserts it
whenever it sees <code>\melody</code>. There's nothing special about
the names – it could be <code>melody</code>, <code>global</code>,
<code>TimeKey</code>,
<code>pianorighthand</code>, or <code>foofoobarbaz</code>. For more details,
see <a href="Saving-typing-with-variables-and-functions.html#Saving-typing-with-variables-and-functions">Saving typing with variables and functions</a>.
Remember that you can use almost any name you like as long
as it contains just alphabetic characters and is distinct from
LilyPond command names. The exact
limitations on variable names are detailed in
<a name="index-File-structure-196"></a><a href="../lilypond/File-structure.html#File-structure">File structure</a>.
<p class="noindent">
<h5 class="subsubheading">See also</h5>
<p class="indent">
<p>For a complete definition of the input format, see
<a name="index-File-structure-197"></a><a href="../lilypond/File-structure.html#File-structure">File structure</a>.
<!-- footer_tag --><br><hr>
<div class="node">
<p>
Next: <a rel="next" accesskey="n" href="Score-is-a-_0028single_0029-compound-musical-expression.html#Score-is-a-_0028single_0029-compound-musical-expression">Score is a (single) compound musical expression</a>,
Up: <a rel="up" accesskey="u" href="How-LilyPond-input-files-work.html#How-LilyPond-input-files-work">How LilyPond input files work</a>
</div>
<div style="background-color: #e8ffe8; padding: 2; border: #c0ffc0 1px solid;">
<p>
<font size="-1">
This page is for LilyPond-2.11.57 (development-branch).
<br>
<address>
Report errors to <a href="http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs">http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs</a>. </address>
<br>
Your <a href="http://lilypond.org/web/devel/participating/documentation-adding">suggestions for the documentation</a> are welcome.
</font>
</p>
</div>
<P>
Other languages: <a href="Introduction-to-the-LilyPond-file-structure.fr.html">français</a>, <a href="Introduction-to-the-LilyPond-file-structure.es.html">español</a>, <a href="Introduction-to-the-LilyPond-file-structure.de.html">deutsch</a>.
<BR>
</P>
</BODY></html>
