1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Putting it all together
3 @chapter Putting it all together
5 This section explains how to use the rest of the documentation and
6 how to solve common problems.
9 * Suggestions for writing LilyPond files::
10 * Extending the templates::
11 * Fixing overlapping notation::
12 * How LilyPond files work::
13 * Score is a single musical expression::
14 * Troubleshooting (taking it all apart)::
18 @node Suggestions for writing LilyPond files
19 @section Suggestions for writing LilyPond files
21 Now you're ready to begin writing larger LilyPond files -- not just the
22 little examples in the tutorial, but whole pieces. But how should you
25 The best answer is ``however you want to do it.'' As long as LilyPond
26 can understand your files and produces the output that you want, it
27 doesn't matter what your files look like. That said, sometimes we
28 make mistakes when writing files. If LilyPond can't understand your
29 files, or produces output that you don't like, how do you fix the
32 Here are a few suggestions that can help you to avoid or fix
36 @item Include @code{\version} numbers in every file. Note that all
37 templates contain a @code{\version "2.6.0"} string. We
38 highly recommend that you always include the @code{\version}, no matter
39 how small your file is. Speaking from personal experience, it's
40 quite frustrating to try to remember which version of LilyPond you were
41 using a few years ago. @code{convert-ly} requires you to declare
42 which version of LilyPond you used.
44 @item Include checks: See @ref{Bar check} and @ref{Octave check}. If you
45 include checks every so often, then if you make a mistake, you can pinpoint
46 it quicker. How often is ``every so often''? It depends on the complexity
47 of the music. For very simple music, perhaps just once or twice. For
48 very complex music, every bar.
50 @item One bar per line. If there is anything complicated, either in the music
51 itself or in the output you desire, it's often good to write only one bar
52 per line. Saving screen space by cramming eight bars per line just isn't
53 worth it if you have to `debug' your files.
55 @item Comment your files, with either bar numbers (every so often) or
56 references to musical themes (``second theme in violins'', ``fourth
57 variation''). You may not need it when you're writing the piece for
58 the first time, but if you want to go back and change something two
59 or three years later, you won't know how your file is structured if you
60 didn't comment the file.
62 @item Ident your braces. A lot of problems are caused by an imbalance
63 in the number of @code{@{} and @code{@}}.
68 @node Extending the templates
69 @section Extending the templates
71 You've read the tutorial, you know how to write music. But how can you
72 get the staves that you want? The templates are ok, but what if you
73 want something that isn't covered?
75 Start off with the template that seems closest to what you want to end
76 up with. Let's say that you want to write something for soprano and
77 cello. In this case, we would start with ``Notes and lyrics'' (for the
82 melody = \relative c' @{
96 \context Voice = one @{
100 \lyricsto "one" \new Lyrics \text
103 \midi @{ \tempo 4=60 @}
107 Now we want to add a cello part. Let's look at the ``Notes only'' example:
111 melody = \relative c' @{
122 \midi @{ \tempo 4=60 @}
126 We don't need two @code{\version} commands. We'll need the @code{melody}
127 section. We don't want two @code{\score} sections -- if we had two
128 @code{\score}s, we'd get the two parts separately. We want them together,
129 as a duet. Within the @code{\score} section, we don't need two
130 @code{\layout} or @code{\midi}.
132 If we simply cut and paste the @code{melody} section, we would end up with
133 two @code{melody} sections. So let's rename them. We'll call the one
134 for the soprano @code{sopranoMusic}, and the one for the cello can be
135 called @code{celloMusic}. While we're doing this, let's rename @code{text}
136 to be @code{sopranoLyrics}. Remember to rename both instances of all
137 these names -- both the initial definition (the
138 @code{melody = relative c' @{ } part) and the name's use (in the
139 @code{\score} section).
141 While we're doing this, let's change the cello part's staff -- celli
142 normally use bass clef. We'll also give the cello some different
147 sopranoMusic = \relative c' @{
155 sopranoLyrics = \lyricmode @{
159 celloMusic = \relative c @{
169 \context Voice = one @{
173 \lyricsto "one" \new Lyrics \sopranoLyrics
176 \midi @{ \tempo 4=60 @}
180 This is looking promising, but the cello part won't appear in the
181 score -- we haven't used it in the @code{\score} section. If we
182 want the cello part to appear under the soprano part, we need to add
185 \new Staff \celloMusic
189 underneath the soprano stuff. We also need to add @code{<<} and
190 @code{>>} around the music -- that tells LilyPond that there's
191 more than one thing (in this case staff) happening at once. The
192 @code{\score} looks like this now
198 \context Voice = one @{
202 \lyricsto "one" \new Lyrics \sopranoLyrics
204 \new Staff \celloMusic
207 \midi @{ \tempo 4=60 @}
212 This looks a bit messy; the indentation is messed up now. That is
213 easily fixed. Here's the complete soprano and cello template.
215 @lilypond[quote,verbatim,raggedright]
217 sopranoMusic = \relative c' {
225 sopranoLyrics = \lyricmode {
229 celloMusic = \relative c {
240 \context Voice = one {
244 \lyricsto "one" \new Lyrics \sopranoLyrics
246 \new Staff \celloMusic
249 \midi { \tempo 4=60 }
255 @node Fixing overlapping notation
256 @section Fixing overlapping notation
258 This may come as a surprise, but LilyPond isn't perfect. Some notation
259 elements can overlap. This is unfortunate, but (in most cases) is easily
262 @lilypond[quote,fragment,raggedright,verbatim,relative=2]
263 e4^\markup{ \italic ritenuto } g b e
268 The easiest solution is to increase the distance between the object
269 (in this case text, but it could easily be fingerings or dynamics
270 instead) and the note. In LilyPond, this is called the
271 @code{padding} property. For most objects, it is around 1.0 or
272 less (it varies with each object). We want to increase it, so let's
275 @lilypond[quote,fragment,raggedright,verbatim,relative=2]
276 \once \override TextScript #'padding = #1.5
277 e4^\markup{ \italic ritenuto } g b e
280 That looks better, but it isn't quite big enough. After experimenting
281 with a few values, we think 2.3 is the best number in this case. However,
282 this number is merely the result of experimentation and my personal
283 taste in notation. Try the above example with 2.3... but also try higher
284 (and lower) numbers. Which do you think looks the best?
288 Another solution gives us complete control over placing the object -- we
289 can move it horizontally or vertically. This is done with the
290 @code{extra-offset} property. It is slightly more complicated and can
291 cause other problems. When we move objects with @code{extra-offset},
292 the movement is done after LilyPond has placed all other objects. This means
293 that the result can overlap with other objects.
295 @lilypond[quote,fragment,raggedright,verbatim,relative=2]
296 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
297 e4^\markup{ \italic ritenuto } g b e
300 With @code{extra-offset}, the first number controls the horizontal
301 movement (left is negative); the second number controls the vertial
302 movement (up is positive). After a bit of experimenting, we decided
303 that these values look good
305 @lilypond[quote,fragment,raggedright,verbatim,relative=2]
306 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
307 e4^\markup{ \italic ritenuto } g b e
311 Again, these numbers are simply the result of a few experiments and
312 looking at the output. You might prefer the text to be slightly higher,
313 or to the left, or whatever. Try it and look at the result!
318 This manual: @ref{The \override command}, @ref{Common tweaks}.
321 @node How LilyPond files work
322 @section How LilyPond files work
324 The LilyPond input format is quite free-form, giving experienced
325 users a lot of flexibility to structure their files however they
326 wish. However, this flexibility can make things confusing for
327 new users. This section will explain some of this structure, but
328 may gloss over some details in favor of simplicity. For a complete
329 description of the input format, see @ref{File structure}.
331 Most examples in this manual are little snippets -- for example
337 As you are (hopefully) aware by now, this will not compile by
338 itself. These examples are shorthand for complete
339 examples. They all need at least curly braces to compile
348 but most examples also make use of the @code{\relative c'}
349 (or @code{c''}) command. This is not necessary to merely
350 compile the examples, but in most cases the output will
351 look very odd if you omit the @code{\relative c'}.
353 @lilypond[quote,fragment,raggedright,verbatim]
359 Now we get to the only real stumbling block: LilyPond
360 input in this form is actually @emph{another}
361 shorthand. Although it compiles and displays the
362 correct output, it is shorthand for
372 A @code{\score} must begin with a single music
373 expression. Remember that a music expression could
374 be anything from a single note to a huge
379 insert the whole score of a Wagner opera in here
385 Since everything is inside @code{@{ ... @}}, it counts
386 as one music expression.
388 The @code{\score} can contain other things, such as
401 Most people put some of those commands outside the
402 @code{\score} block -- for example, @code{\header} is
403 almost always placed above the @code{\score}. That's
404 just another shorthand.
406 Another great shorthand is the ability to define
407 variables. All the templates use this
410 melody = \relative c' @{
419 When LilyPond looks at this file, it takes the value of
420 @code{melody} (ie everything to the right of the
421 @code{melody = }) and inserts it whenever it sees
422 @code{\melody}. There's nothing special about the
423 name @code{melody}, @code{global}, @code{pianorighthand},
424 or @code{foofoobarbaz}. You can use whatever variable
427 For a complete definition
428 of the input format, see @ref{File structure}.
431 @node Score is a single musical expression
432 @section Score is a single musical expression
434 In the previous section, @ref{How LilyPond files work},
435 we saw the general organization of LilyPond input
436 files. But we seemed to skip over the most important
437 part: how do we figure out what to write after
440 We didn't skip over it at all. The big mystery is simply
441 that there @emph{is} no mystery. This line explains it
445 A @code{\score} must begin with a single music expression.
449 You may find it useful to review
450 @ref{Music expressions explained}. In that section, we
451 saw how to build big music expressions from small
452 pieces -- we started from notes, then chords, etc. Now
453 we're going to start from a big music expression and
458 @{ % this brace begins the overall music expression
460 insert the whole score of a Wagner opera in here
462 @} % this brace ends the overall music expression
467 A whole Wagner opera would easily double the length of
468 this manual, so let's just do a singer and piano. We
469 don't need a @code{GrandStaff} for this ensemble, so we
470 shall remove it. We @emph{do} need a singer and a piano,
477 \context Staff = singer @{
479 \context PianoStaff = piano {@
487 Remember that we use @code{<<} and @code{>>} to show
488 simultaneous music. And we definitely want to show
489 the vocal part and piano part at the same time!
495 \context Staff = singer @{
496 \context Voice = vocal @{ @}
497 \lyricsto vocal \new Lyrics @{ @}
499 \context PianoStaff = piano {@
500 \context Staff = upper @{ @}
501 \context Staff = lower @{ @}
509 Now we have a lot more details. We have the singer's
510 staff. It contains a @code{Voice} (in LilyPond, this
511 term refers to a set of notes, not necessarily vocal
512 notes -- for example, a violin generally plays one
513 voice) and some lyrics. The piano contains an upper
514 staff (right hand) and a lower staff (left hand).
516 At this stage, we could start filling in notes. Inside
517 the curly braces next to @code{\context Voice = vocal},
518 we could start writing
526 But if we did that, the @code{\score} section would
527 get pretty long, and it would be harder to understand
528 what was happening. So let's use identifiers (or
539 \context Staff = singer @{
540 \context Voice = vocal @{ \melody @}
541 \lyricsto vocal \new Lyrics @{ \text @}
543 \context PianoStaff = piano {@
544 \context Staff = upper @{ \upper @}
545 \context Staff = lower @{ \lower @}
554 Remember that you can use any names you like.
556 When writing a @code{\score} section, or when reading
557 one, just take it slowly and carefully. Start with
558 the outer layer, then work on each smaller
559 layer. It also really helps to be strict with
560 indentation -- make sure that each item on the same
561 layer starts on the same horizontal position in your
565 @node Troubleshooting (taking it all apart)
566 @section Troubleshooting (taking it all apart)
568 Sooner or later, you will write a file that LilyPond cannot
569 compile. The messages that LilyPond gives may help
570 you find the error, but in many cases you need to do some
571 investigation to determine the source of the problem.
573 The most powerful tool for this purpose is the
574 comment (@code{%} and @code{%@{ ... %@}}). If you don't
575 know where a problem is, start commenting out huge portions
576 of your input file. After you comment out a section, try
577 compiling the file again. If it works, then the problem
578 must exist in the portion you just commented. If it doens't
579 work, then keep on commenting out material until you have
580 something that works.
582 In an extreme case, you might end up with only
595 (in other words, an empty file)
597 If that happens, don't give up. Uncomment a bit -- say,
598 the bass part -- and see if it works. If it doesn't,
599 then comment out all of the bass music (but leave
600 @code{\bass} in the @code{\score} uncommented.
603 bass = \relative c' @{
611 Now start slowly uncommenting more and more of the
612 @code{bass} part until you find the problem line.