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
347 Most examples also make use of the @code{\relative c'}
348 (or @code{c''}) command. This is not necessary to merely
349 compile the examples, but in most cases the output will
350 look very odd if you omit the @code{\relative c'}.
352 @lilypond[quote,fragment,raggedright,verbatim]
358 Now we get to the only real stumbling block: LilyPond
359 input in this form is actually @emph{another}
360 shorthand. Although it compiles and displays the
361 correct output, it is shorthand for
371 A @code{\score} must begin with a single music
372 expression. Remember that a music expression could
373 be anything from a single note to a huge
378 insert the whole score of a Wagner opera in here
384 Since everything is inside @code{@{ ... @}}, it counts
385 as one music expression.
387 The @code{\score} can contain other things, such as
400 Most people put some of those commands outside the
401 @code{\score} block -- for example, @code{\header} is
402 almost always placed above the @code{\score}. That's
403 just another shorthand.
405 Another great shorthand is the ability to define
406 variables. All the templates use this
409 melody = \relative c' @{
418 When LilyPond looks at this file, it takes the value of
419 @code{melody} and inserts it whenever it sees
420 @code{\melody}. There's nothing special about the
421 names -- it could be @code{melody}, @code{global},
422 @code{pianorighthand}, or @code{foofoobarbaz}. You
423 can use whatever variable names you want.
425 For a complete definition
426 of the input format, see @ref{File structure}.
429 @node Score is a single musical expression
430 @section Score is a single musical expression
432 In the previous section, @ref{How LilyPond files work},
433 we saw the general organization of LilyPond input
434 files. But we seemed to skip over the most important
435 part: how do we figure out what to write after
438 We didn't skip over it at all. The big mystery is simply
439 that there @emph{is} no mystery. This line explains it
443 A @code{\score} must begin with a single music expression.
447 You may find it useful to review
448 @ref{Music expressions explained}. In that section, we
449 saw how to build big music expressions from small
450 pieces -- we started from notes, then chords, etc. Now
451 we're going to start from a big music expression and
456 @{ % this brace begins the overall music expression
458 insert the whole score of a Wagner opera in here
460 @} % this brace ends the overall music expression
465 A whole Wagner opera would easily double the length of
466 this manual, so let's just do a singer and piano. We
467 don't need a @code{GrandStaff} for this ensemble, so we
468 shall remove it. We @emph{do} need a singer and a piano,
475 \context Staff = singer @{
477 \context PianoStaff = piano @{
485 Remember that we use @code{<<} and @code{>>} to show
486 simultaneous music. And we definitely want to show
487 the vocal part and piano part at the same time!
493 \context Staff = singer @{
494 \context Voice = vocal @{ @}
495 \lyricsto vocal \new Lyrics @{ @}
497 \context PianoStaff = piano @{
498 \context Staff = upper @{ @}
499 \context Staff = lower @{ @}
507 Now we have a lot more details. We have the singer's
508 staff: it contains a @code{Voice} (in LilyPond, this
509 term refers to a set of notes, not necessarily vocal
510 notes -- for example, a violin generally plays one
511 voice) and some lyrics. We also have a piano staff:
512 it contains an upper staff (right hand) and a lower
515 At this stage, we could start filling in notes. Inside
516 the curly braces next to @code{\context Voice = vocal},
517 we could start writing
525 But if we did that, the @code{\score} section would
526 get pretty long, and it would be harder to understand
527 what was happening. So let's use identifiers (or
538 \context Staff = singer @{
539 \context Voice = vocal @{ \melody @}
540 \lyricsto vocal \new Lyrics @{ \text @}
542 \context PianoStaff = piano @{
543 \context Staff = upper @{ \upper @}
544 \context Staff = lower @{ \lower @}
553 Remember that you can use any names you like.
555 When writing a @code{\score} section, or when reading
556 one, just take it slowly and carefully. Start with
557 the outer layer, then work on each smaller
558 layer. It also really helps to be strict with
559 indentation -- make sure that each item on the same
560 layer starts on the same horizontal position in your
564 @node Troubleshooting (taking it all apart)
565 @section Troubleshooting (taking it all apart)
567 Sooner or later, you will write a file that LilyPond cannot
568 compile. The messages that LilyPond gives may help
569 you find the error, but in many cases you need to do some
570 investigation to determine the source of the problem.
572 The most powerful tool for this purpose is the
573 comment (@code{%} and @code{%@{ ... %@}}). If you don't
574 know where a problem is, start commenting out huge portions
575 of your input file. After you comment out a section, try
576 compiling the file again. If it works, then the problem
577 must exist in the portion you just commented. If it doens't
578 work, then keep on commenting out material until you have
579 something that works.
581 In an extreme case, you might end up with only
595 (in other words, a file without any music)
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 work,
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.