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
9 * How LilyPond files work::
10 * Voices contain music::
11 * Contexts and engravers::
12 * Extending the templates::
17 @node How LilyPond files work
18 @section How LilyPond files work
20 The LilyPond input format is quite free-form, giving experienced
21 users a lot of flexibility to structure their files however they
22 wish. However, this flexibility can make things confusing for new
23 users. This section will explain some of this structure, but may
24 gloss over some details in favor of simplicity. For a complete
25 description of the input format, see @ruser{File structure}.
28 * Introduction to the LilyPond file structure::
29 * Score is a (single) compound musical expression::
30 * Nesting Music Expressions::
33 @node Introduction to the LilyPond file structure
34 @subsection Introduction to the LilyPond file structure
36 A basic example of a lilypond input file is
41 @var{...compound music expression...} % all the music goes here!
49 There are many variations of this basic pattern, but this
50 example serves as a useful starting place.
52 At this point, you may be confused, since you have never seen a
53 @code{\score@{@}} before. This is because LilyPond automatically
54 adds the extra commands when you give it simple input. LilyPond
55 treats input like this:
64 as shorthand for this:
75 In other words, if the input contains a single music expression,
76 LilyPond will interpret the file as though the music expression
77 was wrapped up inside a @code{\score@{@}}.
81 A @code{\score} must begin with a compound music expression.
82 Remember that a music expression could be anything from a single
88 @var{...insert the whole score of a Wagner opera in here...}
94 Since everything is inside @code{@{ ... @}}, it counts
95 as one music expression.
97 As we saw previously, the @code{\score} can contain other things,
110 Some people put some of those commands outside the @code{\score}
111 block -- for example, @code{\header} is often placed above the
112 @code{\score}. That's just another shorthand that LilyPond
119 Another great shorthand is the ability to define variables. All
120 the templates use this
123 melody = \relative c' @{
132 When LilyPond looks at this file, it takes the value of
133 @code{melody} (everything after the equals sign) and inserts it
134 whenever it sees @code{\melody}. There's nothing special about
135 the names -- it could be @code{melody}, @code{global},
136 @code{pianorighthand}, or @code{foofoobarbaz}. You can use
137 whatever variable names you want as along as they contain just
138 alphabetic characters. For more details, see
139 @ruser{Saving typing with variables and functions}.
144 For a complete definition of the input format, see
145 @ruser{File structure}.
147 @node Score is a (single) compound musical expression
148 @subsection Score is a (single) compound musical expression
150 @cindex Compound music expression
151 @cindex Music expression, compound
153 We saw the general organization of LilyPond input files in the
154 previous section, @ref{How LilyPond files work}. But we seemed to
155 skip over the most important part: how do we figure out what to
156 write after @code{\score}?
158 We didn't skip over it at all. The big mystery is simply that
159 there @emph{is} no mystery. This line explains it all:
162 @emph{A @code{\score} must begin with a compound music expression.}
166 You may find it useful to review
167 @ref{Music expressions explained}. In that section, we saw how to
168 build big music expressions from small pieces -- we started from
169 notes, then chords, etc. Now we're going to start from a big
170 music expression and work our way down.
174 @{ % this brace begins the overall compound music expression
176 @var{...insert the whole score of a Wagner opera in here...}
178 @} % this brace ends the overall compound music expression
183 A whole Wagner opera would easily double the length of this
184 manual, so let's just add a singer and piano. We don't need a
185 @code{GrandStaff} for this ensemble, so we shall remove it. We
186 @emph{do} need a singer and a piano, though.
192 \new Staff = "singer" <<
194 \new PianoStaff = piano <<
202 Remember that we use @code{<<} and @code{>>} to show simultaneous
203 music. And we definitely want to show the vocal part and piano
204 part at the same time, not one after the other! However, the
205 @code{<< .. >>} construct is not really necessary for the Singer
206 staff, as it contains only one music expression, but Staves often
207 do require simultaneous Voices within them, so using @code{<< .. >>}
208 rather than braces is a good habit to adopt.
214 \new Staff = "singer" <<
215 \new Voice = "vocal" @{ @}
217 \new Lyrics \lyricsto vocal \new Lyrics @{ @}
218 \new PianoStaff = "piano" <<
219 \new Staff = "upper" @{ @}
220 \new Staff = "lower" @{ @}
228 Now we have a lot more details. We have the singer's staff: it
229 contains a @code{Voice} (in LilyPond, this term refers to a set of
230 notes, not necessarily vocal notes -- for example, a violin
231 generally plays one voice) and some lyrics. We also have a piano
232 staff: it contains an upper staff (right hand) and a lower staff
235 At this stage, we could start filling in notes. Inside the curly
236 braces next to @code{\new Voice = vocal}, we could start writing
244 But if we did that, the @code{\score} section would get pretty
245 long, and it would be harder to understand what was happening. So
246 let's use variables instead.
256 \new Staff = "singer" <<
257 \new Voice = "vocal" @{ \melody @}
259 \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
260 \new PianoStaff = "piano" <<
261 \new Staff = "upper" @{ \upper @}
262 \new Staff = "lower" @{ \lower @}
271 Remember that you can use almost any name you like as long
272 as it contains just alphabetic characters. The exact
273 limitations on variable names are detailed in
274 @ruser{File structure}.
276 When writing (or reading) a @code{\score} section, just take it
277 slowly and carefully. Start with the outer layer, then work on
278 each smaller layer. It also really helps to be strict with
279 indentation -- make sure that each item on the same layer starts
280 on the same horizontal position in your text editor.
283 @node Nesting Music Expressions
284 @subsection Nesting Music Expressions
286 New staves do not have to all be declared at the beginning;
287 they may be introduced temporarily at any point. This is
288 particularly useful for creating ossia sections
289 (see @rglos{ossia}). Here's a simple example showing how
290 to introduce a new staff temporarily for the duration of
293 @lilypond[verbatim,quote,ragged-right]
309 The ossia section may be placed above the staff
312 @lilypond[verbatim,quote,ragged-right]
320 alignAboveContext = "main" }
328 Ossia are often written without clef and without
329 time signature and are usually in a smaller font.
330 These require commands which
331 have not yet been introduced. See ...
332 TODO Add ref to tweaks section where this example should
333 be placed and explained.
335 @lilypond[verbatim,quote,ragged-right]
336 \new Staff = "main" {
340 << % Start main and ossia in parallel
341 { r8 f c c } % Main music
342 \new Staff \with { % Start ossia staff
343 \remove "Clef_engraver"
344 \remove "Time_signature_engraver"
345 % Reduce size of notes and staff
347 \override StaffSymbol #'staff-space = #(magstep -2)
348 alignAboveContext = "main" % Place above main staff
350 { s8 f f c } % Ossia music
351 >> % End parallel music
360 @node Voices contain music
361 @section Voices contain music
363 Singers need voices to sing, and so does LilyPond.
364 The actual music for all instruments in a score
365 is contained in Voices - the most fundamental
366 of all LilyPond's concepts.
369 * I'm hearing Voices::
370 * Explicitly instantiating voices::
371 * Voices and vocals::
374 @node I'm hearing Voices
375 @subsection I'm hearing Voices
379 @cindex Voice context
381 The lowest, most fundamental or innermost layers in a LilyPond
382 score are called Voices. Voices are sometimes
383 called @q{layers} in other notation packages. In LilyPond they
384 are called @q{Voice contexts}.
386 In fact, a Voice layer or context is the only one which can
387 contain music. If a Voice context is not explicitly declared
388 one is created automatically. Some instruments such as an
389 Oboe can play only one note at a time and music written for
390 such instruments is monophonic and requires just a single
391 voice. Instruments which can play more than one note at a
392 time like the piano will often require multiple voices to
393 encode the different concurent notes and rhythms they are
396 A single voice can contain many notes in a chord, of course,
397 so when exactly are multiple voices needed?
398 Let us analyse a short piece of music to see how many voices
399 are required. Here are the notes from the first two bars
400 of the second of Chopin's Deux Nocturnes, Op 32.
402 @c The following should appear as music without code
403 @lilypond[quote,ragged-right]
404 \new Staff \relative c'' {
412 \once \override NoteColumn #'force-hshift = #0 <ees c>2
413 \once \override NoteColumn #'force-hshift = #0.5 des2 }
419 The direction of the stems is often used to indicate the
420 continuity of two simultaneous melodic lines. Here the
421 stems of the highest notes are all pointing up and the
422 stems of the lower notes are all pointing down.
423 This is the first indication that more than one voice
426 But the real need for multiple voices arises when notes
427 which start at the same time have different durations.
428 Look at the notes which start at beat three in the first
429 bar. The a-flat is a dotted quarter note, the f is a
430 quarter note and the d-flat is a half note. These
431 cannot be written as a chord as all the notes in a chord
432 must have the same duration. Neither can they be written
433 as sequential notes, as they must start at the same time.
434 This section of the bar requires three voices, and the
435 normal practice would be to write the whole bar as three
436 voices, as shown here, where we have used different notehead
437 and colors for the three voices.
439 @c The following should appear as music without code
440 @c The three voice styles should be defined in -init
441 @lilypond[quote,ragged-right]
442 \new Staff \relative c'' {
453 \once \override NoteColumn #'force-hshift = #0 <ees c>2
454 \once \override NoteColumn #'force-hshift = #0.5 des2 }
460 Let us see how this is done.
464 The easiest way to enter fragments with more than one voice on a
465 staff is to enter each voice as a sequence (with @code{@{...@}}),
466 and combine them simultaneously with angle brackets, @code{<<...>>}.
467 The fragments must also be separated with double backward slashes,
468 @code{\\}, to place them in separate voices. Without these, the
469 notes would be entered into a single voice, which would usually
470 cause errors. This technique is particularly suited to pieces of
471 music which are largely monophonic with occasional short sections
472 of polyphony. Here's a simple example:
474 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
476 % Voice "1" Voice "2"
477 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
478 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
479 << { a2. r4 } \\ { fis2. s4 } >>
482 This example has just two voices, but the same contruct may be
483 used to encode three or more voices by adding more back-slash
486 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
487 In each of these contexts, vertical direction of slurs, stems, ties,
488 dynamics etc., is set appropriately.
490 @lilypond[quote,verbatim,fragment]
491 \new Staff \relative c' {
494 % Voice "1" Voice "2" Voice "3"
495 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
496 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
500 These voices are all separate from the main voice that contains
501 the notes just outside the @code{<< \\ >>} construct. Let's call
502 this the @emph{simultaneous construct}. Slurs and ties may only
503 connect notes within the same voice, so slurs and ties cannot go
504 into or out of a simultaneous construct. Conversely,
505 parallel voices from separate simultaneous constructs on the same
506 staff are the same voice. Other voice- related properties also
507 carry across simultaneous constructs. Here is the same example,
508 with different colors and noteheads for each voice. Note that
509 changes in one Voice do not affect other voices, but they do
510 persist in the same Voice later. Note also that tied notes may be
511 split across the same voices in two constructs, shown here in the
514 @lilypond[quote,verbatim]
515 \new Staff \relative c' {
525 { c8 b16 a b8 g ~ g2 } \\
532 Polyphony does not change the relationship of notes within a
533 @code{\relative @{ @}} block. Each note is calculated relative to
534 the note immediately preceding it, or to the first note of the
538 \relative c' @{ noteA << <noteB noteC> \\ noteD >> noteE @}
541 @code{noteB} is relative to @code{noteA}
543 @code{noteC} is relative to @code{noteB}, not @code{noteA};
545 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
548 @code{noteE} is relative to @code{noteD}, not @code{noteA}
550 We are now in a position to return to the first example from
551 the Chopin Nocturne to see how this might be encoded. As we
552 shall see, this encounters some difficulties. We begin as
553 we have learnt, using the @code{<< \\ >>} construct to
554 enter the music of the first bar in three voices:
556 @lilypond[quote,verbatim,fragment,ragged-right]
557 \new Staff \relative c'' {
560 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
571 The stem directions are automatically assigned with the
572 odd-numbered voices taking upward stems and the even-numbered
573 voices downward ones. The stems for voices 1 and 2 are right,
574 but the stems in voice 3 should go down in this particular piece
575 of music. We can correct this
576 by telling LilyPond that this third voice is really a fourth
577 voice, with stems going down, using the @code{\voiceFour}
578 command. There are also corresponding @code{\voiceOne},
579 @code{\voiceTwo} and @code{voiceThree} commands.
580 This result in the following:
582 @lilypond[quote,verbatim,fragment,ragged-right]
583 \new Staff \relative c'' {
588 { \voiceFour <ees c>2 des2 }
595 and exposes a problem commonly encountered with multiple
596 voices: the stems of notes can collide with noteheads
597 in other voices. In laying out the notes, LilyPond allows the
598 notes or chords from two voices to occupy the same vertical
599 note column provided the stems are in opposite directions, but
600 the notes from a third voice are displaced to avoid the stems
601 colliding. This often works well, but in this example the
602 notes of the third voice are clearly not well placed by default.
603 LilyPond provides several ways to adjust the horizontal placing
604 of notes. We are not quite ready yet to see how to correct this,
605 so we shall leave this problem until a later section (see ... )
607 FIXME: Move the following words and example into Tweaks or
608 somewhere more suitable, leaving just a ref here. -td
610 Ways or correcting horizontal placings are described fully
611 in the Notation Reference.
612 We introduce just one here, the @code{force-hshift} property of
613 @code{NoteColumn}. The lower two notes of the first chord (i.e,
614 those in the third voice) should not be shifted away from the
615 note column of the higher two notes. To correct this we set
616 @code{force-hshift} of these notes to zero.
617 The lower note of the second chord is best placed just to the
618 right of the higher notes. We achieve this by setting
619 @code{force-hshift} of this note to 0.5, ie half a notehead's
620 width to the right of the note column of the higher notes.
622 Here's the final result:
624 @lilypond[quote,verbatim,fragment,ragged-right]
625 \new Staff \relative c'' {
631 \once \override NoteColumn #'force-hshift = #0 <ees c>2
632 \once \override NoteColumn #'force-hshift = #0.5 des2
639 @node Explicitly instantiating voices
640 @subsection Explicitly instantiating voices
642 Voice contexts can also be created manually
643 inside a @code{<< >>} block to create polyphonic music, using
644 @code{\voiceOne}, up to @code{\voiceFour} to automatically assign
645 the directions of stems, slurs, etc.
647 Specifically, the construct @code{<< \\ >>} which we used in
648 the previous section:
651 << \upper \\ \lower >>
655 where @code{upper} and @code{lower} are user-defined variables
656 containing the music for the two voices, is equivalent to
660 \new Voice = "1" @{ \voiceOne \upper @}
661 \new Voice = "2" @{ \voiceTwo \lower @}
665 The @code{\voiceXXX} commands set the direction of stems, slurs,
666 ties, articulations, text annotations, augmentation dots of dotted
667 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
668 make these objects point upwards, while @code{\voiceTwo} and
669 @code{\voiceFour} make them point downwards. These commands also
670 generate a horizontal shift for each voice when this is required
671 to avoid clashes of note heads. The command @code{\oneVoice}
672 reverts the settings back to the normal values for a single voice.
674 An expression that appears directly inside a @code{<< >>} belongs
675 to the main voice. This is useful when extra voices appear while
676 the main voice is playing. Here is a more correct rendition of
677 the example from the previous section. The red diamond-shaped
678 notes demonstrate that the main melody is now in a single
679 voice context, permitting a phrasing slur to be drawn over them.
681 @lilypond[quote,ragged-right,verbatim]
682 \new Staff \relative c' {
684 c16^( d e f % These notes are monophonic
685 << % Start simultaneous section of three voices
686 { g4 f e | d2 e2) } % Continue the main voice in parallel
687 \new Voice { % Initiate second voice
688 \voiceTwo % Set stems, etc, down
689 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
691 \new Voice { % Initiate third voice
692 \voiceThree % Set stems, etc, up
699 @cindex nesting music expressions
700 @cindex nesting simultaneous constructs
702 More deeply nested polyphony constructs are possible, and if a
703 voice appears only briefly this might be a more natural way to
706 @lilypond[quote,ragged-right,verbatim]
707 \new Staff \relative c' {
727 This method of nesting new voices briefly is useful
728 when only small sections of the music
729 are polyphonic, but when the whole staff is largely polyphonic
730 it can be clearer to use multiple voices throughout, using
731 spacing notes to step over sections where the voice is silent,
734 @lilypond[quote,ragged-right,verbatim]
735 \new Staff \relative c' <<
736 \new Voice { % Initiate first voice
738 c16^( d e f g4 f e | d2 e2) |
740 \new Voice { % Initiate second voice
741 \voiceTwo % set stems, etc down
742 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
744 \new Voice { % Initiate third voice
745 \voiceThree % set stems, etc up
753 @node Voices and vocals
754 @subsection Voices and vocals
756 Vocal music presents a special difficulty: we need to combine two
757 expressions -- notes and lyrics.
759 You have already seen the @code{\lyricsAdd@{@}} command, which
760 handles simple cases for you. However, this technique is
761 very limited. For most music, you must explicitly link the lyrics
762 to the notes with @code{\lyricsto@{@}}, using the name assigned
765 @lilypond[quote,verbatim,fragment]
767 \new Voice = "one" \relative c'' {
770 c4 b8. a16 g4. f8 e4 d c2
772 \new Lyrics \lyricsto "one" {
773 No more let sins and sor -- rows grow.
778 Let us reuse the earlier example from Judas Maccabæus to
779 illustrate this more flexible technique. We first recast
780 it to use variables so the music and lyrics can be separated
781 from the staff structure. We also introduce a choirstaff
782 bracket. The lyrics themselves must be introduced with
783 @code{\lyricmode} to ensure they are interpreted as lyrics
786 @lilypond[quote,verbatim]
787 global = { \time 6/8 \partial 8 \key f \major}
788 SopOneMusic = \relative c'' {
789 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
790 SopTwoMusic = \relative c' {
791 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
792 SopOneLyrics = \lyricmode {
793 Let | flee -- cy flocks the | hills a -- dorn, __ }
794 SopTwoLyrics = \lyricmode {
795 Let | flee -- cy flocks the | hills a -- dorn, }
800 \new Voice = "SopOne" {
804 \new Lyrics \lyricsto "SopOne" {
809 \new Voice = "SopTwo" {
812 \new Lyrics \lyricsto "SopTwo" {
820 This is the basic structure of all vocal scores. More staves may
821 be added as required, more voices may be added to the staves,
822 more verses may be added to the lyrics,
823 and the variables containing the music can easily be placed
824 in separate files should they become too long.
826 Here is a final example of the first line of a hymn with four
827 verses, set for SATB. In this case the words for all four
830 @lilypond[quote,verbatim]
831 global = { \time 4/4 \partial 4 \key c \major}
832 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
833 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
834 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
835 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
836 VerseOne = \lyricmode {
837 E -- | ter -- nal fa -- ther, | strong to save, }
838 VerseTwo = \lyricmode {
839 O | Christ, whose voice the | wa -- ters heard, }
840 VerseThree = \lyricmode {
841 O | Ho -- ly Spi -- rit, | who didst brood }
842 VerseFour = \lyricmode {
843 O | Tri -- ni -- ty of | love and pow'r }
849 \new Voice = "Sop" { \voiceOne \global \SopMusic }
850 \new Voice = "Alto" { \voiceTwo \AltoMusic }
851 \new Lyrics \lyricsto "Sop" { \VerseOne }
852 \new Lyrics \lyricsto "Sop" { \VerseTwo }
853 \new Lyrics \lyricsto "Sop" { \VerseThree }
854 \new Lyrics \lyricsto "Sop" { \VerseFour }
858 \new Voice = "Tenor" { \voiceOne \TenorMusic }
859 \new Voice = "Bass" { \voiceTwo \BassMusic }
865 @node Contexts and engravers
866 @section Contexts and engravers
868 Contexts and engravers have been mentioned informally
869 in earlier sections; we now must look at
870 these concepts in more detail, as they are important
871 in the fine-tuning of LilyPond output.
875 * Contexts explained::
876 * Creating contexts::
878 * Modifying Contexts::
879 * On the un-nestedness of brackets and ties::
882 @node Contexts explained
883 @subsection Contexts explained
885 When music is printed, a lot of notational elements must be added to the
886 output. For example, compare the input and output of the following example:
888 @lilypond[quote,verbatim,relative=2,fragment]
892 The input is rather sparse, but in the output, bar lines, accidentals,
893 clef, and time signature are added. LilyPond @emph{interprets} the
894 input. During this step, the musical information is inspected in time
895 order, similar to reading a score from left to right. While reading
896 the input, the program remembers where measure boundaries are, and which
897 pitches require explicit accidentals. This information must be held on
898 several levels. For example, the effect of an accidental is limited
899 to a single staff, while a bar line must be synchronized across the
902 Within LilyPond, these rules and bits of information are grouped in
903 @emph{Contexts}. Some examples of contexts are @context{Voice},
904 @context{Staff}, and @context{Score}. They are hierarchical to
905 reflect the heirarchical nature of a musical score. For
906 example: a @context{Staff} can contain many @context{Voice}s, and a
907 @context{Score} can contain many @context{Staff} contexts.
910 @image{context-example,5cm,,}
913 Each context has the responsibility for enforcing some notation rules,
914 creating some notation objects and maintaining the associated
915 properties. For example, the @context{Voice} context may introduce an
916 accidental and then the @context{Staff} context maintains the rule to
917 show or suppress the accidental for the remainder of the measure. The
918 synchronization of bar lines is handled in the @context{Score} context.
920 However, in some music we may not want the bar lines to be
921 synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
922 such cases, we must modify the default settings of the @context{Score}
923 and @context{Staff} contexts.
925 For very simple scores, contexts are created implicitly, and you need
926 not be aware of them. For larger pieces, such as anything with more
927 than one staff, they must be
928 created explicitly to make sure that you get as many staves as you
929 need, and that they are in the correct order. For typesetting pieces
930 with specialized notation, it can be useful to modify existing or
931 to define new contexts.
933 In addition to the @context{Score}, @context{Staff} and
934 @context{Voice} contexts there are contexts which fit between
935 the score and staff levels to control staff groups, such as the
936 @context{PianoStaff} and @context{ChoirStaff} contexts. There
937 are also alternative staff and voice contexts, and contexts for
938 lyrics, percussion, fret boards, figured bass, etc. A complete
939 list is shown in the Notation Reference.
942 The names of all context types are formed from one or more
943 words, each word being capitalised and joined immediately to the
944 preceding word with no hyphen or underscore, e.g.,
945 @context{GregorianTranscriptionStaff}.
947 @node Creating contexts
948 @subsection Creating contexts
950 The top level context, @context{Score}, is created with the
951 @code{\score} command, or automatically in simple scores.
953 For scores with only one voice and one staff, the @context{Voice}
954 and @context{Staff} contexts may be left to be created
955 automatically, but for more complex scores it is necessary to
956 create @context{Staff} and @context{Voice} contexts by hand.
957 The simplest command that does this is @code{\new}.
958 It is prepended to a music expression, for example
962 @cindex Context, creating
965 \new @var{type} @var{music expression}
969 where @var{type} is a context name (like @code{Staff} or
970 @code{Voice}). This command creates a new context, and starts
971 interpreting the @var{music expression} with that.
973 Note that there is no @code{\new Score % Invalid!} command;
974 a @context{Score} context is introduced with @code{\score}.
975 This is because there can be only one @context{Score}
976 context, whereas there may be multiple @context{Staff}
977 and @context{Voice} contexts - each created by an @code{\new}.
979 So a practical application of @code{\new} is a score with many
980 staves. Each part that should be on its own staff, is preceded
981 with @code{\new Staff}.
983 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
990 The @code{\new} command may also give a identifying name to the
991 context to distinguish it from other contexts of the same type,
994 \new @var{type} = @var{id} @var{music}
997 Note the distinction between the name of the context type,
998 @context{Staff}, @context{Voice}, etc, and
999 the identifying name of a particular instance of that type,
1000 which can be any sequence of letters invented by the user.
1001 The identifying name is used to refer back to that particular
1002 instance of a context. We saw this in use in the section on
1003 lyrics in @ref{Voices and vocals}.
1007 @subsection Engravers
1009 Every mark on the printed output of a score produced by LilyPond
1010 is produced by an @code{Engraver}. Thus there is an engraver
1011 to print staves, one to print noteheads, one for stems, one for
1012 beams, etc, etc. In total there are over 120 such engravers!
1013 Fortunately, for most scores it is not necessary to know more than
1014 a few, and for simple scores you do not need to know about any.
1016 A musical score can be viewed heirarchically. At the top level
1017 is the whole score. This consists of one or more staves.
1018 Each staff contains one or more voices. As we have seen, there
1019 are contexts which correspond to each of these levels and it
1020 is in these contexts that the Engravers operate.
1022 Engravers such as the @code{Metronome_mark_engraver}, whose
1023 action and output applies to the score as a whole, live in
1024 the highest level Context - the @context{Score} context. There
1025 can be only one of these engravers as there is only one tempo
1026 at any particular point in the score.
1028 The @code{Clef_engraver} and @code{Key_engraver} are to be
1029 found in the Staff Context, as different staves may require
1030 different clefs and keys.
1032 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1033 in a context at the Voice level, the lowest level of all.
1035 Each engraver processes the particular objects associated
1036 with its function, and contain the properties that relate
1037 to that function. These properties, like the properties
1038 associated with contexts, may be modified to change the
1039 operation of the engraver or the appearance of those elements
1040 in the printed score.
1042 Engravers all have compound names formed from words which
1043 describe their function. Just the first word is capitalised,
1044 and the remainder are joined to it with underscores. Thus
1045 the @code{Staff_symbol_engraver} is responsible for creating the
1046 lines of the staff, the @code{Clef_engraver} determines and sets
1047 the pitch reference point on the staff by drawing a clef symbol.
1049 Here are some of the most common engravers together with their
1050 function. You will see it is easy to guess the function from
1051 the name, or vice versa.
1053 @multitable @columnfractions .3 .7
1056 @item Accidental_engraver
1057 @tab Makes accidentals, cautionary and suggested accidentals
1062 @item Dynamic_engraver
1063 @tab Creates hairpins and dynamic texts
1065 @tab Creates the key signature
1066 @item Metronome_mark_engraver
1067 @tab Engraves metronome marking
1068 @item Note_heads_engraver
1069 @tab Engraves noteheads
1072 @item Staff_symbol_engraver
1073 @tab Engraves the five (by default) lines of the staff
1075 @tab Creates stems and single-stem tremulos
1078 We shall see later how the output of LilyPond can be changed
1079 by modifying the action of Engravers.
1082 @node Modifying Contexts
1083 @subsection Modifying Contexts
1085 TODO: write section, including \with, \remove, \consists
1090 @c my name start sucking the more docs I write. -gp
1091 @node On the un-nestedness of brackets and ties
1092 @subsection On the un-nestedness of brackets and ties
1094 Different kinds of brackets and ties may be mixed freely,
1096 TODO: improve this example
1098 @lilypond[quote,verbatim,fragment,ragged-right]
1100 r16[ g16 \times 2/3 {r16 e'8] }
1101 g16( a \times 2/3 {b d e') }
1102 g8[( a \times 2/3 {b d') e'~]}
1103 \times 4/5 {e'32\( a b d' e'} a'4.\)
1107 TODO... add more info? Fluff up the first sentence?
1110 @node Extending the templates
1111 @section Extending the templates
1113 You've read the tutorial, you know how to write music. But how can you
1114 get the staves that you want? The templates are ok, but what if you
1115 want something that isn't covered?
1118 * Soprano and cello::
1119 * Four-part SATB vocal score::
1120 * Building a score from scratch::
1123 @node Soprano and cello
1124 @subsection Soprano and cello
1126 Start off with the template that seems closest to what you want to end
1127 up with. Let's say that you want to write something for soprano and
1128 cello. In this case, we would start with @q{Notes and lyrics} (for the
1133 melody = \relative c' @{
1141 text = \lyricmode @{
1147 \new Voice = "one" @{
1151 \new Lyrics \lyricsto "one" \text
1158 Now we want to add a cello part. Let's look at the @q{Notes only} example:
1162 melody = \relative c' @{
1177 We don't need two @code{\version} commands. We'll need the @code{melody}
1178 section. We don't want two @code{\score} sections -- if we had two
1179 @code{\score}s, we'd get the two parts separately. We want them together,
1180 as a duet. Within the @code{\score} section, we don't need two
1181 @code{\layout} or @code{\midi}.
1183 If we simply cut and paste the @code{melody} section, we would end up with
1184 two @code{melody} sections. So let's rename them. We'll call the section
1185 for the soprano @code{sopranoMusic} and the section for the cello
1186 @code{celloMusic}. While we're doing this, let's rename @code{text}
1187 to be @code{sopranoLyrics}. Remember to rename both instances of all
1188 these names -- both the initial definition (the
1189 @code{melody = relative c' @{ } part) and the name's use (in the
1190 @code{\score} section).
1192 While we're doing this, let's change the cello part's staff -- celli
1193 normally use bass clef. We'll also give the cello some different
1198 sopranoMusic = \relative c' @{
1206 sopranoLyrics = \lyricmode @{
1210 celloMusic = \relative c @{
1220 \new Voice = "one" @{
1224 \new Lyrics \lyricsto "one" \sopranoLyrics
1231 This is looking promising, but the cello part won't appear in the
1232 score -- we haven't used it in the @code{\score} section. If we
1233 want the cello part to appear under the soprano part, we need to add
1236 \new Staff \celloMusic
1240 underneath the soprano stuff. We also need to add @code{<<} and
1241 @code{>>} around the music -- that tells LilyPond that there's
1242 more than one thing (in this case, @code{Staff}) happening at once. The
1243 @code{\score} looks like this now
1249 \new Voice = "one" @{
1253 \new Lyrics \lyricsto "one" \sopranoLyrics
1255 \new Staff \celloMusic
1263 This looks a bit messy; the indentation is messed up now. That is
1264 easily fixed. Here's the complete soprano and cello template.
1266 @lilypond[quote,verbatim,ragged-right]
1268 sopranoMusic = \relative c' {
1276 sopranoLyrics = \lyricmode {
1280 celloMusic = \relative c {
1291 \new Voice = "one" {
1295 \new Lyrics \lyricsto "one" \sopranoLyrics
1297 \new Staff \celloMusic
1305 @node Four-part SATB vocal score
1306 @subsection Four-part SATB vocal score
1308 Most vocal scores of music written for four-part mixed choir
1309 with orchestral accompaniment such as Mendelssohn's Elijah or
1310 Handel's Messiah have the choral music and words on four
1311 staves, one for each of SATB, with a piano reduction of the
1312 orchestral accompaniment underneath. Here's an example:
1314 @c The following should appear as music without code
1315 @lilypond[quote,ragged-right]
1317 global = { \key d \major \time 4/4 }
1318 sopMusic = \relative c'' {
1320 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1322 sopWords = \lyricmode {
1323 Wor -- thy is the lamb that was slain
1325 altoMusic = \relative a' {
1327 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1329 altoWords = \sopWords
1330 tenorMusic = \relative c' {
1332 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1334 tenorWords = \sopWords
1335 bassMusic = \relative c' {
1337 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1339 bassWords = \sopWords
1340 upper = \relative a' {
1343 r4 <a d fis>2 <a e' a>4 |
1344 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1345 <g cis g'>4 <a d fis> <a cis e>2 |
1347 lower = \relative c, {
1350 <d d'>4 <d d'>2 <cis cis'>4 |
1351 <b b'>4. <b' b'>8 <fis fis'>2 |
1352 <e e'>4 <d d'> <a' a'>2 |
1356 << % combine ChoirStaff and PianoStaff in parallel
1358 \new Staff = "sopranos" <<
1359 \set Staff.instrumentName = "Soprano"
1360 \new Voice = "sopranos" { \global \sopMusic }
1362 \new Lyrics \lyricsto "sopranos" { \sopWords }
1363 \new Staff = "altos" <<
1364 \set Staff.instrumentName = "Alto"
1365 \new Voice = "altos" { \global \altoMusic }
1367 \new Lyrics \lyricsto "altos" { \altoWords }
1368 \new Staff = "tenors" <<
1369 \set Staff.instrumentName = "Tenor"
1370 \new Voice = "tenors" { \global \tenorMusic }
1372 \new Lyrics \lyricsto "tenors" { \tenorWords }
1373 \new Staff = "basses" <<
1374 \set Staff.instrumentName = "Bass"
1375 \new Voice = "basses" { \global \bassMusic }
1377 \new Lyrics \lyricsto "basses" { \bassWords }
1381 \set PianoStaff.instrumentName = "Piano "
1382 \new Staff = "upper" \upper
1383 \new Staff = "lower" \lower
1389 None of the templates provides this layout exactly. The
1390 nearest is @q{SATB vocal score and automatic piano reduction},
1391 but we shall need to change the layout and add a piano
1392 accompaniment which is not derived automatically from the
1393 vocal parts. The variables holding the music and words for
1394 the vocal parts are fine, but we shall need to add variables for
1395 the piano reduction.
1397 The order in which the contexts appear in the ChoirStaff of
1398 the template do not correspond with the order in the vocal
1399 score shown above. We need to rearrange them so there are
1400 four staves with the words written directly underneath the
1401 notes for each part.
1402 All the voices should be @code{voiceOne}, which is
1403 the default, so the @code{\voiceXXX} commands can be removed.
1404 We also need to specify the tenor clef for the tenors.
1405 The way in which lyrics are specified has also been simplified
1406 as we have not yet encountered the method in the template so
1407 far. We've also added the names of each staff.
1409 Doing this gives for our ChoirStaff:
1413 \new Staff = "sopranos" <<
1414 \set Staff.instrumentName = "Soprano"
1415 \new Voice = "sopranos" @{ \global \sopMusic @}
1417 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1418 \new Staff = "altos" <<
1419 \set Staff.instrumentName = "Alto"
1420 \new Voice = "altos" @{ \global \altoMusic @}
1422 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1423 \new Staff = "tenors" <<
1424 \set Staff.instrumentName = "Tenor"
1425 \new Voice = "tenors" @{ \global \tenorMusic @}
1427 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1428 \new Staff = "basses" <<
1429 \set Staff.instrumentName = "Bass"
1430 \new Voice = "basses" @{ \global \bassMusic @}
1432 \new Lyrics \lyricsto "basses" @{ \bassWords @}
1436 Next we must work out the piano part. This is
1437 easy - we just pull out the piano part from the
1438 @q{Solo piano} template:
1442 \set PianoStaff.instrumentName = "Piano "
1443 \new Staff = "upper" \upper
1444 \new Staff = "lower" \lower
1448 and add the variable definitions for @code{upper}
1451 The ChoirStaff and PianoStaff must be combined
1452 using angle brackets as we want them to be
1453 stacked one above the other:
1456 << % combine ChoirStaff and PianoStaff in parallel
1458 \new Staff = "sopranos" <<
1459 \new Voice = "sopranos" @{ \global \sopMusic @}
1461 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
1462 \new Staff = "altos" <<
1463 \new Voice = "altos" @{ \global \altoMusic @}
1465 \new Lyrics \lyricsto "altos" @{ \altoWords @}
1466 \new Staff = "tenors" <<
1467 \clef "G_8" % tenor clef
1468 \new Voice = "tenors" @{ \global \tenorMusic @}
1470 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
1471 \new Staff = "basses" <<
1473 \new Voice = "basses" @{ \global \bassMusic @}
1475 \new Lyrics \lyricsto "basses" @{ bassWords @}
1479 \set PianoStaff.instrumentName = "Piano "
1480 \new Staff = "upper" \upper
1481 \new Staff = "lower" \lower
1486 Combining all these together and adding the music
1487 for the three bars of the example above gives:
1489 @lilypond[quote,verbatim,ragged-right]
1491 global = { \key d \major \time 4/4 }
1492 sopMusic = \relative c'' {
1494 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
1496 sopWords = \lyricmode {
1497 Wor -- thy is the lamb that was slain
1499 altoMusic = \relative a' {
1501 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
1503 altoWords = \sopWords
1504 tenorMusic = \relative c' {
1506 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
1508 tenorWords = \sopWords
1509 bassMusic = \relative c' {
1511 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
1513 bassWords = \sopWords
1514 upper = \relative a' {
1517 r4 <a d fis>2 <a e' a>4 |
1518 <d fis d'>4. <d fis d'>8 <a d a'>2 |
1519 <g cis g'>4 <a d fis> <a cis e>2 |
1521 lower = \relative c, {
1524 <d d'>4 <d d'>2 <cis cis'>4 |
1525 <b b'>4. <b' b'>8 <fis fis'>2 |
1526 <e e'>4 <d d'> <a' a'>2 |
1530 << % combine ChoirStaff and PianoStaff in parallel
1532 \new Staff = "sopranos" <<
1533 \set Staff.instrumentName = "Soprano"
1534 \new Voice = "sopranos" { \global \sopMusic }
1536 \new Lyrics \lyricsto "sopranos" { \sopWords }
1537 \new Staff = "altos" <<
1538 \set Staff.instrumentName = "Alto"
1539 \new Voice = "altos" { \global \altoMusic }
1541 \new Lyrics \lyricsto "altos" { \altoWords }
1542 \new Staff = "tenors" <<
1543 \set Staff.instrumentName = "Tenor"
1544 \new Voice = "tenors" { \global \tenorMusic }
1546 \new Lyrics \lyricsto "tenors" { \tenorWords }
1547 \new Staff = "basses" <<
1548 \set Staff.instrumentName = "Bass"
1549 \new Voice = "basses" { \global \bassMusic }
1551 \new Lyrics \lyricsto "basses" { \bassWords }
1555 \set PianoStaff.instrumentName = "Piano "
1556 \new Staff = "upper" \upper
1557 \new Staff = "lower" \lower
1564 @node Building a score from scratch
1565 @subsection Building a score from scratch
1567 After gaining some facility with writing LilyPond code you
1568 may find that it is easier to build a score from scratch
1569 rather than modifying one of the templates. You can also
1570 develop your own style this way to suit the sort of music you
1571 like. Let's see how to put together the score for an organ
1572 prelude as an example.
1574 We begin with a header section. Here go the title, name
1575 of composer, etc followed by the variable definitions
1576 and ending with the score block. Let's start with these and
1577 fill in the details later.
1579 We'll use the first two bars of Bach's prelude
1580 based on @emph{Jesu, meine Freude} which is set in two
1581 manuals and pedal organ. The top manual has two voices,
1582 the lower and pedal organ one each. So we need four
1583 music definitions and one to define the time signature
1589 title = "Jesu, meine Freude"
1590 composer = "J S Bach"
1592 TimeKey = @{ \time 4/4 \key c \minor @}
1593 ManualOneVoiceOneMusic = @{s1@}
1594 ManualOneVoiceTwoMusic = @{s1@}
1595 ManualTwoMusic = @{s1@}
1596 PedalOrganMusic = @{s1@}
1602 For now we've just used a spacer note, @code{s1},
1603 instead of the real music. We'll add that later.
1605 Next let's see what should go in the score block.
1606 This just mirrors the staff structure we want.
1607 Organ music is usually written on three staves,
1608 one for each manual and one for the pedals. The
1609 manual staves should be bracketed together so we
1610 need to use a PianoStaff for them.
1614 \new Staff = "ManualOne" <<
1615 \new Voice @{ \ManualOneVoiceOneMusic @}
1616 \new Voice @{ \ManualOneVoiceTwoMusic @}
1617 >> % end ManualOne Staff context
1618 \new Staff = "ManualTwo" <<
1619 \new Voice @{ \ManualTwoMusic @}
1620 >> % end ManualTwo Staff context
1621 >> % end PianoStaff context
1624 Next we need to add a staff for the pedal organ.
1625 This goes underneath the PianoStaff, but it must
1626 be simultaneous with it, so we need angle brackets
1630 << % PianoStaff and Pedal Staff must be simultaneous
1632 \new Staff = "ManualOne" <<
1633 \new Voice @{ \ManualOneVoiceOneMusic @}
1634 \new Voice @{ \ManualOneVoiceTwoMusic @}
1635 >> % end ManualOne Staff context
1636 \new Staff = "ManualTwo" <<
1637 \new Voice @{ \ManualTwoMusic @}
1638 >> % end ManualTwo Staff context
1639 >> % end PianoStaff context
1640 \new Staff = "PedalOrgan" <<
1641 \new Voice @{ \PedalOrganMusic @}
1646 It is not strictly necessary to use the simultaneous contruct
1647 @code{<< >>} for the manual two staff and the pedal organ staff,
1648 since they contain only one music expression, but it does no harm
1649 and always using angle brackets after @code{\new Staff} is a good
1650 habit to cultivate in case there are multiple voices.
1652 Let's add this structure to the score block, and adjust the
1653 indenting. We also add the appropriate clefs, ensure the
1654 second voice stems point down with @code{\voiceTwo} and
1655 enter the time signature and key to each staff using our
1656 predefined variable, \TimeKey.
1660 << % PianoStaff and Pedal Staff must be simultaneous
1662 \new Staff = "ManualOne" <<
1663 \TimeKey % set time signature and key
1665 \new Voice @{ \ManualOneVoiceOneMusic @}
1666 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
1667 >> % end ManualOne Staff context
1668 \new Staff = "ManualTwo" <<
1671 \new Voice @{ \ManualTwoMusic @}
1672 >> % end ManualTwo Staff context
1673 >> % end PianoStaff context
1674 \new Staff = "PedalOrgan" <<
1677 \new Voice @{ \PedalOrganMusic @}
1678 >> % end PedalOrgan Staff
1680 @} % end Score context
1683 That completes the structure. Any three-staff organ music
1684 will have a similar structure, although the number of voices
1685 may vary. All that remains now
1686 is to add the music, and combine all the parts together.
1688 @lilypond[quote,verbatim,ragged-right]
1691 title = "Jesu, meine Freude"
1692 composer = "J S Bach"
1694 TimeKey = { \time 4/4 \key c \minor }
1695 ManualOneVoiceOneMusic = \relative g' {
1696 g4 g f ees | d2 c2 |
1698 ManualOneVoiceTwoMusic = \relative c' {
1699 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
1700 c c4 b8 c8. g16 c b c d |
1702 ManualTwoMusic = \relative c' {
1703 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
1704 f ees f d g aes g f ees d e8~ ees16 f ees d |
1706 PedalOrganMusic = \relative c {
1707 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
1708 r16 g ees f g f g8 c,2 |
1712 << % PianoStaff and Pedal Staff must be simultaneous
1714 \new Staff = "ManualOne" <<
1715 \TimeKey % set time signature and key
1717 \new Voice { \ManualOneVoiceOneMusic }
1718 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
1719 >> % end ManualOne Staff context
1720 \new Staff = "ManualTwo" <<
1723 \new Voice { \ManualTwoMusic }
1724 >> % end ManualTwo Staff context
1725 >> % end PianoStaff context
1726 \new Staff = "PedalOrgan" <<
1729 \new Voice { \PedalOrganMusic }
1730 >> % end PedalOrgan Staff
1732 } % end Score context
1735 @node Scores and parts
1736 @section Scores and parts
1738 TODO: this is really old stuff from the really old tutorial.
1739 Rewrite, fix, etc. Or maybe delete entirely. -gp
1740 Include section on tags -td
1742 In orchestral music, all notes are printed twice. Once in a part for
1743 the musicians, and once in a full score for the conductor. Variables can
1744 be used to avoid double work. The music is entered once, and stored in
1745 a variable. The contents of that variable is then used to generate
1746 both the part and the full score.
1748 It is convenient to define the notes in a special file. For example,
1749 suppose that the file @file{horn-music.ly} contains the following part
1750 of a horn/@/bassoon duo
1753 hornNotes = \relative c @{
1760 Then, an individual part is made by putting the following in a file
1763 \include "horn-music.ly"
1765 instrument = "Horn in F"
1769 \transpose f c' \hornNotes
1776 \include "horn-music.ly"
1780 substitutes the contents of @file{horn-music.ly} at this position in
1781 the file, so @code{hornNotes} is defined afterwards. The command
1782 @code{\transpose f@tie{}c'} indicates that the argument, being
1783 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
1784 @code{f} is denoted by notated @code{c'}, which corresponds with the
1785 tuning of a normal French Horn in@tie{}F. The transposition can be seen
1786 in the following output
1788 @lilypond[quote,ragged-right]
1789 \transpose f c' \relative c {
1795 In ensemble pieces, one of the voices often does not play for many
1796 measures. This is denoted by a special rest, the multi-measure
1797 rest. It is entered with a capital @code{R} followed by a duration
1798 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
1799 etc.). By multiplying the
1800 duration, longer rests can be constructed. For example, this rest
1801 takes 3@tie{}measures in 2/4 time
1807 When printing the part, multi-rests
1808 must be condensed. This is done by setting a run-time variable
1811 \set Score.skipBars = ##t
1815 This command sets the property @code{skipBars} in the
1816 @code{Score} context to true (@code{##t}). Prepending the rest and
1817 this option to the music above, leads to the following result
1819 @lilypond[quote,ragged-right]
1820 \transpose f c' \relative c {
1822 \set Score.skipBars = ##t
1829 The score is made by combining all of the music together. Assuming
1830 that the other voice is in @code{bassoonNotes} in the file
1831 @file{bassoon-music.ly}, a score is made with
1834 \include "bassoon-music.ly"
1835 \include "horn-music.ly"
1838 \new Staff \hornNotes
1839 \new Staff \bassoonNotes
1846 @lilypond[quote,ragged-right]
1854 r4 d,8 f | gis4 c | b bes |
1855 a8 e f4 | g d | gis f