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.7.32"} 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 of text. 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{@}}.
67 If you are entering music from an existing score (ie typesetting a
68 piece of existing sheet music),
72 @item Enter one manuscript (the physical copy) system at a time (but still
73 only one bar per line of text), and
74 check each system when you finish it. You may use the
75 @code{showLastLength} command to speed up processing -- see
76 @ref{Skipping corrected music}.
78 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
79 in the input file whenever the manuscript has a line break. This
80 makes it much easier to compare the LilyPond music to the original
81 music. When you are finished proofreading your score, you may
82 define @code{mBreak = @{ @}} to remove all those line breaks. This
83 will allow LilyPond to place line breaks wherever it feels are
89 @node Extending the templates
90 @section Extending the templates
92 You've read the tutorial, you know how to write music. But how can you
93 get the staves that you want? The templates are ok, but what if you
94 want something that isn't covered?
96 Start off with the template that seems closest to what you want to end
97 up with. Let's say that you want to write something for soprano and
98 cello. In this case, we would start with ``Notes and lyrics'' (for the
103 melody = \relative c' @{
117 \new Voice = "one" @{
121 \new Lyrics \lyricsto "one" \text
124 \midi @{ \tempo 4=60 @}
128 Now we want to add a cello part. Let's look at the ``Notes only'' example:
132 melody = \relative c' @{
143 \midi @{ \tempo 4=60 @}
147 We don't need two @code{\version} commands. We'll need the @code{melody}
148 section. We don't want two @code{\score} sections -- if we had two
149 @code{\score}s, we'd get the two parts separately. We want them together,
150 as a duet. Within the @code{\score} section, we don't need two
151 @code{\layout} or @code{\midi}.
153 If we simply cut and paste the @code{melody} section, we would end up with
154 two @code{melody} sections. So let's rename them. We'll call the one
155 for the soprano @code{sopranoMusic}, and the one for the cello can be
156 called @code{celloMusic}. While we're doing this, let's rename @code{text}
157 to be @code{sopranoLyrics}. Remember to rename both instances of all
158 these names -- both the initial definition (the
159 @code{melody = relative c' @{ } part) and the name's use (in the
160 @code{\score} section).
162 While we're doing this, let's change the cello part's staff -- celli
163 normally use bass clef. We'll also give the cello some different
168 sopranoMusic = \relative c' @{
176 sopranoLyrics = \lyricmode @{
180 celloMusic = \relative c @{
190 \new Voice = "one" @{
194 \new Lyrics \lyricsto "one" \sopranoLyrics
197 \midi @{ \tempo 4=60 @}
201 This is looking promising, but the cello part won't appear in the
202 score -- we haven't used it in the @code{\score} section. If we
203 want the cello part to appear under the soprano part, we need to add
206 \new Staff \celloMusic
210 underneath the soprano stuff. We also need to add @code{<<} and
211 @code{>>} around the music -- that tells LilyPond that there's
212 more than one thing (in this case staff) happening at once. The
213 @code{\score} looks like this now
219 \new Voice = "one" @{
223 \new Lyrics \lyricsto "one" \sopranoLyrics
225 \new Staff \celloMusic
228 \midi @{ \tempo 4=60 @}
233 This looks a bit messy; the indentation is messed up now. That is
234 easily fixed. Here's the complete soprano and cello template.
236 @lilypond[quote,verbatim,ragged-right]
238 sopranoMusic = \relative c' {
246 sopranoLyrics = \lyricmode {
250 celloMusic = \relative c {
265 \new Lyrics \lyricsto "one" \sopranoLyrics
267 \new Staff \celloMusic
270 \midi { \tempo 4=60 }
276 @node Fixing overlapping notation
277 @section Fixing overlapping notation
279 This may come as a surprise, but LilyPond isn't perfect. Some notation
280 elements can overlap. This is unfortunate, but (in most cases) is easily
283 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
284 e4^\markup{ \italic ritenuto } g b e
289 The easiest solution is to increase the distance between the object
290 (in this case text, but it could easily be fingerings or dynamics
291 instead) and the note. In LilyPond, this is called the
292 @code{padding} property; it is measured in staff spaces. For most
293 objects, this value is around 1.0 or less (it varies with each
294 object). We want to increase it, so let's try 1.5
296 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
297 \once \override TextScript #'padding = #1.5
298 e4^\markup{ \italic ritenuto } g b e
301 That looks better, but it isn't quite big enough. After experimenting
302 with a few values, we think 2.3 is the best number in this case. However,
303 this number is merely the result of experimentation and my personal
304 taste in notation. Try the above example with 2.3... but also try higher
305 (and lower) numbers. Which do you think looks the best?
309 Another solution gives us complete control over placing the object -- we
310 can move it horizontally or vertically. This is done with the
311 @code{extra-offset} property. It is slightly more complicated and can
312 cause other problems. When we move objects with @code{extra-offset},
313 the movement is done after LilyPond has placed all other objects. This means
314 that the result can overlap with other objects.
316 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
317 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
318 e4^\markup{ \italic ritenuto } g b e
321 With @code{extra-offset}, the first number controls the horizontal
322 movement (left is negative); the second number controls the vertial
323 movement (up is positive). After a bit of experimenting, we decided
324 that these values look good
326 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
327 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
328 e4^\markup{ \italic ritenuto } g b e
332 Again, these numbers are simply the result of a few experiments and
333 looking at the output. You might prefer the text to be slightly higher,
334 or to the left, or whatever. Try it and look at the result!
339 This manual: @ref{The \override command}, @ref{Common tweaks}.
342 @node How LilyPond files work
343 @section How LilyPond files work
345 The LilyPond input format is quite free-form, giving experienced
346 users a lot of flexibility to structure their files however they
347 wish. However, this flexibility can make things confusing for
348 new users. This section will explain some of this structure, but
349 may gloss over some details in favor of simplicity. For a complete
350 description of the input format, see @ref{File structure}.
352 Most examples in this manual are little snippets -- for example
358 As you are (hopefully) aware by now, this will not compile by
359 itself. These examples are shorthand for complete
360 examples. They all need at least curly braces to compile
368 Most examples also make use of the @code{\relative c'}
369 (or @code{c''}) command. This is not necessary to merely
370 compile the examples, but in most cases the output will
371 look very odd if you omit the @code{\relative c'}.
373 @lilypond[quote,fragment,ragged-right,verbatim]
379 Now we get to the only real stumbling block: LilyPond
380 input in this form is actually @emph{another}
381 shorthand. Although it compiles and displays the
382 correct output, it is shorthand for
392 A @code{\score} must begin with a single music
393 expression. Remember that a music expression could
394 be anything from a single note to a huge
399 insert the whole score of a Wagner opera in here
405 Since everything is inside @code{@{ ... @}}, it counts
406 as one music expression.
408 The @code{\score} can contain other things, such as
421 Most people put some of those commands outside the
422 @code{\score} block -- for example, @code{\header} is
423 almost always placed above the @code{\score}. That's
424 just another shorthand.
426 Another great shorthand is the ability to define
427 variables. All the templates use this
430 melody = \relative c' @{
439 When LilyPond looks at this file, it takes the value of
440 @code{melody} (everything after the equals sign) and
441 inserts it whenever it sees
442 @code{\melody}. There's nothing special about the
443 names -- it could be @code{melody}, @code{global},
444 @code{pianorighthand}, or @code{foofoobarbaz}. You
445 can use whatever variable names you want.
447 For a complete definition
448 of the input format, see @ref{File structure}.
451 @node Score is a single musical expression
452 @section Score is a single musical expression
454 In the previous section, @ref{How LilyPond files work},
455 we saw the general organization of LilyPond input
456 files. But we seemed to skip over the most important
457 part: how do we figure out what to write after
460 We didn't skip over it at all. The big mystery is simply
461 that there @emph{is} no mystery. This line explains it
465 A @code{\score} must begin with a single music expression.
469 You may find it useful to review
470 @ref{Music expressions explained}. In that section, we
471 saw how to build big music expressions from small
472 pieces -- we started from notes, then chords, etc. Now
473 we're going to start from a big music expression and
478 @{ % this brace begins the overall music expression
480 insert the whole score of a Wagner opera in here
482 @} % this brace ends the overall music expression
487 A whole Wagner opera would easily double the length of
488 this manual, so let's just do a singer and piano. We
489 don't need a @code{GrandStaff} for this ensemble, so we
490 shall remove it. We @emph{do} need a singer and a piano,
497 \new Staff = "singer" <<
499 \new PianoStaff = piano <<
507 Remember that we use @code{<<} and @code{>>} to show
508 simultaneous music. And we definitely want to show
509 the vocal part and piano part at the same time!
515 \new Staff = "singer" <<
516 \new Voice = "vocal" @{ @}
518 \new Lyrics \lyricsto vocal \new Lyrics @{ @}
519 \new PianoStaff = "piano" <<
520 \new Staff = "upper" @{ @}
521 \new Staff = "lower" @{ @}
529 Now we have a lot more details. We have the singer's
530 staff: it contains a @code{Voice} (in LilyPond, this
531 term refers to a set of notes, not necessarily vocal
532 notes -- for example, a violin generally plays one
533 voice) and some lyrics. We also have a piano staff:
534 it contains an upper staff (right hand) and a lower
537 At this stage, we could start filling in notes. Inside
538 the curly braces next to @code{\new Voice = vocal},
539 we could start writing
547 But if we did that, the @code{\score} section would
548 get pretty long, and it would be harder to understand
549 what was happening. So let's use identifiers (or
560 \new Staff = "singer" <<
561 \new Voice = "vocal" @{ \melody @}
563 \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
564 \new PianoStaff = "piano" <<
565 \new Staff = "upper" @{ \upper @}
566 \new Staff = "lower" @{ \lower @}
575 Remember that you can use almost any name you like. The
576 limitations on identifier names are detailed in
577 @ref{File structure}.
579 When writing a @code{\score} section, or when reading
580 one, just take it slowly and carefully. Start with
581 the outer layer, then work on each smaller
582 layer. It also really helps to be strict with
583 indentation -- make sure that each item on the same
584 layer starts on the same horizontal position in your
588 @node Troubleshooting (taking it all apart)
589 @section Troubleshooting (taking it all apart)
591 Sooner or later, you will write a file that LilyPond cannot
592 compile. The messages that LilyPond gives may help
593 you find the error, but in many cases you need to do some
594 investigation to determine the source of the problem.
596 The most powerful tools for this purpose are the
597 single line comment (indicated by @code{%}) and the block
598 comment (indicated by @code{%@{ ... %@}}). If you don't
599 know where a problem is, start commenting out huge portions
600 of your input file. After you comment out a section, try
601 compiling the file again. If it works, then the problem
602 must exist in the portion you just commented. If it doesn't
603 work, then keep on commenting out material until you have
604 something that works.
606 In an extreme case, you might end up with only
620 (in other words, a file without any music)
622 If that happens, don't give up. Uncomment a bit -- say,
623 the bass part -- and see if it works. If it doesn't work,
624 then comment out all of the bass music (but leave
625 @code{\bass} in the @code{\score} uncommented.
628 bass = \relative c' @{
636 Now start slowly uncommenting more and more of the
637 @code{bass} part until you find the problem line.