1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 @node Fundamental concepts
5 @chapter Fundamental concepts
8 * File structure (introduction)::
9 * How LilyPond files work::
10 * Score is a single musical expression::
14 @node File structure (introduction)
15 @section File structure (introduction)
17 A basic example of a lilypond input file is
22 @{ @} % this is a single music expression;
23 % all the music goes in here.
31 There are many variations of this basic pattern, but this
32 example serves as a useful starting place.
34 The major part of this manual is concerned with entering various
35 forms of music in LilyPond. However, many music expressions are not
36 valid input on their own, for example, a @code{.ly} file containing
43 will result in a parsing error. Instead, music should be inside other
44 expressions, which may be put in a file by themselves. Such
45 expressions are called toplevel expressions; see @ruser{File structure}, for
46 a list of all such expressions.
49 @node How LilyPond files work
50 @section How LilyPond files work
52 The LilyPond input format is quite free-form, giving experienced
53 users a lot of flexibility to structure their files however they
54 wish. However, this flexibility can make things confusing for
55 new users. This section will explain some of this structure, but
56 may gloss over some details in favor of simplicity. For a complete
57 description of the input format, see @ruser{File structure}.
59 Most examples in this manual are little snippets -- for example
65 As you are (hopefully) aware by now, this will not compile by
66 itself. These examples are shorthand for complete
67 examples. They all need at least curly braces to compile
75 Most examples also make use of the @code{\relative c'}
76 (or @code{c''}) command. This is not necessary to merely
77 compile the examples, but in most cases the output will
78 look very odd if you omit the @code{\relative c'}.
80 @lilypond[quote,fragment,ragged-right,verbatim]
86 Now we get to the only real stumbling block: LilyPond
87 input in this form is actually @emph{another}
88 shorthand. Although it compiles and displays the
89 correct output, it is shorthand for
99 A @code{\score} must begin with a single music
100 expression. Remember that a music expression could
101 be anything from a single note to a huge
106 insert the whole score of a Wagner opera in here
112 Since everything is inside @code{@{ ... @}}, it counts
113 as one music expression.
115 The @code{\score} can contain other things, such as
127 Some people put some of those commands outside the
128 @code{\score} block -- for example, @code{\header} is
129 often placed above the @code{\score}. That's just
130 another shorthand that LilyPond accepts.
135 Another great shorthand is the ability to define
136 variables. All the templates use this
139 melody = \relative c' @{
148 When LilyPond looks at this file, it takes the value of
149 @code{melody} (everything after the equals sign) and
150 inserts it whenever it sees
151 @code{\melody}. There's nothing special about the
152 names -- it could be @code{melody}, @code{global},
153 @code{pianorighthand}, or @code{foofoobarbaz}. You
154 can use whatever variable names you want. For
156 @ruser{Saving typing with identifiers and functions}.
158 For a complete definition
159 of the input format, see @ruser{File structure}.
162 @node Score is a single musical expression
163 @section Score is a single musical expression
165 In the previous section, @ruser{How LilyPond files work},
166 we saw the general organization of LilyPond input
167 files. But we seemed to skip over the most important
168 part: how do we figure out what to write after
171 We didn't skip over it at all. The big mystery is simply
172 that there @emph{is} no mystery. This line explains it
176 @emph{A @code{\score} must begin with a single music expression.}
180 You may find it useful to review
181 @ruser{Music expressions explained}. In that section, we
182 saw how to build big music expressions from small
183 pieces -- we started from notes, then chords, etc. Now
184 we're going to start from a big music expression and
189 @{ % this brace begins the overall music expression
191 insert the whole score of a Wagner opera in here
193 @} % this brace ends the overall music expression
198 A whole Wagner opera would easily double the length of
199 this manual, so let's just do a singer and piano. We
200 don't need a @code{GrandStaff} for this ensemble, so we
201 shall remove it. We @emph{do} need a singer and a piano,
208 \new Staff = "singer" <<
210 \new PianoStaff = piano <<
218 Remember that we use @code{<<} and @code{>>} to show
219 simultaneous music. And we definitely want to show
220 the vocal part and piano part at the same time!
226 \new Staff = "singer" <<
227 \new Voice = "vocal" @{ @}
229 \new Lyrics \lyricsto vocal \new Lyrics @{ @}
230 \new PianoStaff = "piano" <<
231 \new Staff = "upper" @{ @}
232 \new Staff = "lower" @{ @}
240 Now we have a lot more details. We have the singer's
241 staff: it contains a @code{Voice} (in LilyPond, this
242 term refers to a set of notes, not necessarily vocal
243 notes -- for example, a violin generally plays one
244 voice) and some lyrics. We also have a piano staff:
245 it contains an upper staff (right hand) and a lower
248 At this stage, we could start filling in notes. Inside
249 the curly braces next to @code{\new Voice = vocal},
250 we could start writing
258 But if we did that, the @code{\score} section would
259 get pretty long, and it would be harder to understand
260 what was happening. So let's use identifiers (or
271 \new Staff = "singer" <<
272 \new Voice = "vocal" @{ \melody @}
274 \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
275 \new PianoStaff = "piano" <<
276 \new Staff = "upper" @{ \upper @}
277 \new Staff = "lower" @{ \lower @}
286 Remember that you can use almost any name you like. The
287 limitations on identifier names are detailed in
288 @ruser{File structure}.
290 When writing a @code{\score} section, or when reading
291 one, just take it slowly and carefully. Start with
292 the outer layer, then work on each smaller
293 layer. It also really helps to be strict with
294 indentation -- make sure that each item on the same
295 layer starts on the same horizontal position in your