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. 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 public domain music),
72 @item Enter one manuscript (the physical copy) line at a time, and
73 check each line when you finish it. You may use the
74 @code{showLastLength} command to speed up processing -- see
75 @ref{Skipping corrected music}.
77 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
78 in the input file whenever the manuscript has a line break. This
79 makes it much easier to compare the LilyPond music to the original
80 music. When you are finished proofreading your score, you may
81 define @code{mBreak = @{ @}} to remove all those line breaks. This
82 will allow LilyPond to place line breaks wherever it feels are
88 @node Extending the templates
89 @section Extending the templates
91 You've read the tutorial, you know how to write music. But how can you
92 get the staves that you want? The templates are ok, but what if you
93 want something that isn't covered?
95 Start off with the template that seems closest to what you want to end
96 up with. Let's say that you want to write something for soprano and
97 cello. In this case, we would start with ``Notes and lyrics'' (for the
102 melody = \relative c' @{
116 \context Voice = one @{
120 \lyricsto "one" \new Lyrics \text
123 \midi @{ \tempo 4=60 @}
127 Now we want to add a cello part. Let's look at the ``Notes only'' example:
131 melody = \relative c' @{
142 \midi @{ \tempo 4=60 @}
146 We don't need two @code{\version} commands. We'll need the @code{melody}
147 section. We don't want two @code{\score} sections -- if we had two
148 @code{\score}s, we'd get the two parts separately. We want them together,
149 as a duet. Within the @code{\score} section, we don't need two
150 @code{\layout} or @code{\midi}.
152 If we simply cut and paste the @code{melody} section, we would end up with
153 two @code{melody} sections. So let's rename them. We'll call the one
154 for the soprano @code{sopranoMusic}, and the one for the cello can be
155 called @code{celloMusic}. While we're doing this, let's rename @code{text}
156 to be @code{sopranoLyrics}. Remember to rename both instances of all
157 these names -- both the initial definition (the
158 @code{melody = relative c' @{ } part) and the name's use (in the
159 @code{\score} section).
161 While we're doing this, let's change the cello part's staff -- celli
162 normally use bass clef. We'll also give the cello some different
167 sopranoMusic = \relative c' @{
175 sopranoLyrics = \lyricmode @{
179 celloMusic = \relative c @{
189 \context Voice = one @{
193 \lyricsto "one" \new Lyrics \sopranoLyrics
196 \midi @{ \tempo 4=60 @}
200 This is looking promising, but the cello part won't appear in the
201 score -- we haven't used it in the @code{\score} section. If we
202 want the cello part to appear under the soprano part, we need to add
205 \new Staff \celloMusic
209 underneath the soprano stuff. We also need to add @code{<<} and
210 @code{>>} around the music -- that tells LilyPond that there's
211 more than one thing (in this case staff) happening at once. The
212 @code{\score} looks like this now
218 \context Voice = one @{
222 \lyricsto "one" \new Lyrics \sopranoLyrics
224 \new Staff \celloMusic
227 \midi @{ \tempo 4=60 @}
232 This looks a bit messy; the indentation is messed up now. That is
233 easily fixed. Here's the complete soprano and cello template.
235 @lilypond[quote,verbatim,ragged-right]
237 sopranoMusic = \relative c' {
245 sopranoLyrics = \lyricmode {
249 celloMusic = \relative c {
260 \context Voice = one {
264 \lyricsto "one" \new Lyrics \sopranoLyrics
266 \new Staff \celloMusic
269 \midi { \tempo 4=60 }
275 @node Fixing overlapping notation
276 @section Fixing overlapping notation
278 This may come as a surprise, but LilyPond isn't perfect. Some notation
279 elements can overlap. This is unfortunate, but (in most cases) is easily
282 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
283 e4^\markup{ \italic ritenuto } g b e
288 The easiest solution is to increase the distance between the object
289 (in this case text, but it could easily be fingerings or dynamics
290 instead) and the note. In LilyPond, this is called the
291 @code{padding} property. For most objects, it is around 1.0 or
292 less (it varies with each object). We want to increase it, so let's
295 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
296 \once \override TextScript #'padding = #1.5
297 e4^\markup{ \italic ritenuto } g b e
300 That looks better, but it isn't quite big enough. After experimenting
301 with a few values, we think 2.3 is the best number in this case. However,
302 this number is merely the result of experimentation and my personal
303 taste in notation. Try the above example with 2.3... but also try higher
304 (and lower) numbers. Which do you think looks the best?
308 Another solution gives us complete control over placing the object -- we
309 can move it horizontally or vertically. This is done with the
310 @code{extra-offset} property. It is slightly more complicated and can
311 cause other problems. When we move objects with @code{extra-offset},
312 the movement is done after LilyPond has placed all other objects. This means
313 that the result can overlap with other objects.
315 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
316 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
317 e4^\markup{ \italic ritenuto } g b e
320 With @code{extra-offset}, the first number controls the horizontal
321 movement (left is negative); the second number controls the vertial
322 movement (up is positive). After a bit of experimenting, we decided
323 that these values look good
325 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
326 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
327 e4^\markup{ \italic ritenuto } g b e
331 Again, these numbers are simply the result of a few experiments and
332 looking at the output. You might prefer the text to be slightly higher,
333 or to the left, or whatever. Try it and look at the result!
338 This manual: @ref{The \override command}, @ref{Common tweaks}.
341 @node How LilyPond files work
342 @section How LilyPond files work
344 The LilyPond input format is quite free-form, giving experienced
345 users a lot of flexibility to structure their files however they
346 wish. However, this flexibility can make things confusing for
347 new users. This section will explain some of this structure, but
348 may gloss over some details in favor of simplicity. For a complete
349 description of the input format, see @ref{File structure}.
351 Most examples in this manual are little snippets -- for example
357 As you are (hopefully) aware by now, this will not compile by
358 itself. These examples are shorthand for complete
359 examples. They all need at least curly braces to compile
367 Most examples also make use of the @code{\relative c'}
368 (or @code{c''}) command. This is not necessary to merely
369 compile the examples, but in most cases the output will
370 look very odd if you omit the @code{\relative c'}.
372 @lilypond[quote,fragment,ragged-right,verbatim]
378 Now we get to the only real stumbling block: LilyPond
379 input in this form is actually @emph{another}
380 shorthand. Although it compiles and displays the
381 correct output, it is shorthand for
391 A @code{\score} must begin with a single music
392 expression. Remember that a music expression could
393 be anything from a single note to a huge
398 insert the whole score of a Wagner opera in here
404 Since everything is inside @code{@{ ... @}}, it counts
405 as one music expression.
407 The @code{\score} can contain other things, such as
420 Most people put some of those commands outside the
421 @code{\score} block -- for example, @code{\header} is
422 almost always placed above the @code{\score}. That's
423 just another shorthand.
425 Another great shorthand is the ability to define
426 variables. All the templates use this
429 melody = \relative c' @{
438 When LilyPond looks at this file, it takes the value of
439 @code{melody} (everything after the equals sign) and
440 inserts it whenever it sees
441 @code{\melody}. There's nothing special about the
442 names -- it could be @code{melody}, @code{global},
443 @code{pianorighthand}, or @code{foofoobarbaz}. You
444 can use whatever variable names you want.
446 For a complete definition
447 of the input format, see @ref{File structure}.
450 @node Score is a single musical expression
451 @section Score is a single musical expression
453 In the previous section, @ref{How LilyPond files work},
454 we saw the general organization of LilyPond input
455 files. But we seemed to skip over the most important
456 part: how do we figure out what to write after
459 We didn't skip over it at all. The big mystery is simply
460 that there @emph{is} no mystery. This line explains it
464 A @code{\score} must begin with a single music expression.
468 You may find it useful to review
469 @ref{Music expressions explained}. In that section, we
470 saw how to build big music expressions from small
471 pieces -- we started from notes, then chords, etc. Now
472 we're going to start from a big music expression and
477 @{ % this brace begins the overall music expression
479 insert the whole score of a Wagner opera in here
481 @} % this brace ends the overall music expression
486 A whole Wagner opera would easily double the length of
487 this manual, so let's just do a singer and piano. We
488 don't need a @code{GrandStaff} for this ensemble, so we
489 shall remove it. We @emph{do} need a singer and a piano,
496 \context Staff = singer <<
498 \context PianoStaff = piano <<
506 Remember that we use @code{<<} and @code{>>} to show
507 simultaneous music. And we definitely want to show
508 the vocal part and piano part at the same time!
514 \context Staff = singer <<
515 \context Voice = vocal @{ @}
517 \new Lyrics \lyricsto vocal \new Lyrics @{ @}
518 \context PianoStaff = piano <<
519 \context Staff = upper @{ @}
520 \context Staff = lower @{ @}
528 Now we have a lot more details. We have the singer's
529 staff: it contains a @code{Voice} (in LilyPond, this
530 term refers to a set of notes, not necessarily vocal
531 notes -- for example, a violin generally plays one
532 voice) and some lyrics. We also have a piano staff:
533 it contains an upper staff (right hand) and a lower
536 At this stage, we could start filling in notes. Inside
537 the curly braces next to @code{\context Voice = vocal},
538 we could start writing
546 But if we did that, the @code{\score} section would
547 get pretty long, and it would be harder to understand
548 what was happening. So let's use identifiers (or
559 \context Staff = singer <<
560 \context Voice = vocal @{ \melody @}
562 \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
563 \context PianoStaff = piano <<
564 \context Staff = upper @{ \upper @}
565 \context Staff = lower @{ \lower @}
574 Remember that you can use almost any name you like. The
575 limitations on identifier names are detailed in
576 @ref{File structure}.
578 When writing a @code{\score} section, or when reading
579 one, just take it slowly and carefully. Start with
580 the outer layer, then work on each smaller
581 layer. It also really helps to be strict with
582 indentation -- make sure that each item on the same
583 layer starts on the same horizontal position in your
587 @node Troubleshooting (taking it all apart)
588 @section Troubleshooting (taking it all apart)
590 Sooner or later, you will write a file that LilyPond cannot
591 compile. The messages that LilyPond gives may help
592 you find the error, but in many cases you need to do some
593 investigation to determine the source of the problem.
595 The most powerful tools for this purpose are the
596 single line comment (indicated by @code{%}) and the block
597 comment (indicated by @code{%@{ ... %@}}). If you don't
598 know where a problem is, start commenting out huge portions
599 of your input file. After you comment out a section, try
600 compiling the file again. If it works, then the problem
601 must exist in the portion you just commented. If it doesn't
602 work, then keep on commenting out material until you have
603 something that works.
605 In an extreme case, you might end up with only
619 (in other words, a file without any music)
621 If that happens, don't give up. Uncomment a bit -- say,
622 the bass part -- and see if it works. If it doesn't work,
623 then comment out all of the bass music (but leave
624 @code{\bass} in the @code{\score} uncommented.
627 bass = \relative c' @{
635 Now start slowly uncommenting more and more of the
636 @code{bass} part until you find the problem line.