1 @c -*- coding: utf-8; mode: texinfo; fill-column: 60 -*-
4 Translation of GIT committish: b275aa092642adb798079f7853309e2f5e4383ce
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
11 @c Translator: Jan Nieuwenhuizen
12 @c Translation checker:
13 @c Translation checker committish:
17 @node Fundamentele concepten
18 @translationof Fundamental concepts
19 @chapter Fundamentele concepten
21 In het Leerboek hebben we gezien hoe je prachtig geprinte
22 muziek maakt van een eenvoudig tekstbestand. Dit hoofdstuk
23 introduceert de achterliggende concepten en benodigde
24 technieken voor het maken van ingewikkeldere partituren die
25 er net zo mooi uitzien.
28 * Hoe LilyPond-invoerbestanden werken::
29 * Voices contain music::
30 * Contexts and engravers::
31 * Extending the templates::
35 @node Hoe LilyPond-invoerbestanden werken
36 @translationof How LilyPond input files work
37 @section Hoe LilyPond-invoerbestanden werken
39 Het LilyPond invoerformaat is tamelijk vrij, wat ervaren
40 gebruikers veel flexibiliteit geeft hun bestanden te
41 structureren zoals ze dat wensen. Deze flexibiliteit kan
42 verwarrend zijn voor nieuwe gebruikers. Deze paragraaf legt
43 het een en ander uit over deze structuur. Om het leesbaar
44 te houden worden details weggelaten. Een complete
45 beschrijving van het invoerformaat is te vinden in
46 @ruser{File structure}.
49 * Inleiding in de LilyPond-bestandsstructuur::
50 * Score is a (single) compound musical expression::
51 * Nesting music expressions::
52 * On the un-nestedness of brackets and ties::
55 @node Inleiding in de LilyPond-bestandsstructuur
56 @translationof Introduction to the LilyPond file structure
57 @subsection Inleiding in de LilyPond-bestandsstructuur
60 @cindex bestandsstructuur
62 Een basisvoorbeeld van een LilyPond-invoerbestand is
65 \version @w{"@version{}"}
68 @var{...samengestelde muziekuitdrukking...} % alle muziek komt hier!
75 Er zijn veel variaties op dit basispatroon maar dit
76 voorbeeld dient als een handig beginpunt.
85 Tot nu toe heeft geen van de voorbeelden het
86 @code{\score@{@}}-commando gebruikt. Dit kan omdat LilyPond
87 automatisch de extra commando's toevoegt die benodigt zijn
88 als je het eenvoudige invoer geeft. LilyPond behandelt invoer
98 als een afkorting voor dit:
115 Anders gezegd, als de invoer een enkelvoudige
116 muziekuitdrukking bevat, interpreteert LilyPond het bestand
117 alsof die muziekuitdrukking ingepakt is in bovenstaande
120 @cindex impliciete contexten
121 @cindex contexten, impliciet
123 @strong{Een kleine waarschuwing!} In veel van de voorbeelden
124 in de LilyPond-documentatie worden de @code{\new Staff}- en
125 @code{\new Voice}-commando's weggelaten en worden ze
126 impliciet aangemaakt. Voor eenvoudige voorbeelden werkt dat
127 goed, maar voor ingewikkelde voorbeelden, vooral wanneer
128 additionele commando's worden gebruikt, kan het impliciete
129 aanmaken van contexten verrassende resultaten opleveren,
130 zoals extra ongewenste notebalken. Hoe je contexten
131 expliciet specificeert, wordt uitgelegd in @ref{Contexts and
134 @warning{Voor het invoeren van meer dan enkele regels muziek
135 wordt aangeraden altijd notenbalken en stemmen expliciet te
138 Laten we terugkeren naar het eerste voorbeeld en het
139 @code{\score}-commando beter bekijken.
141 Een @code{\score}-blok moet altijd precies één
142 muziekuitdrukking bevatten, en die moet direct na het
143 @code{\score}-commando staan. Herrinner je dat een
144 muziekuitdrukking alles kan zijn van een enkele noot
145 tot een enorme samengestelde uitdrukking zoals
150 @var{...vul de volledige partituur van een Wagner opera hier in...}
156 Omdat alles tussen @code{@{ ... @}} staat, telt het als één
159 Zoals we eerder al zagen, kan het @code{\score}-blok
160 allerlei andere dingen bevatten, zoals
182 Merk op dat deze drie commando's -- @code{\header},
183 @code{\layout} en @code{\midi} -- speciaal zijn: in
184 tegenstelling tot veel andere commando's die met een
185 backslash (@code{\}) beginnen zijn het @emph{geen}
186 muziekuitdrukkingen en ze zijn ook geen onderdeel van een
187 muziekuitdrukking. Ze kunnen zowel binnen als buiten het
188 @code{\score}-blok worden geplaatst. Deze commando's worden
189 gewoonlijk dan ook buiten het @code{\score}-blok gezet
190 -- bijvoorbeeld, @code{\header} staat meestal boven het
191 @code{\score}-commando, zoals het in eerste voorbeeld van
194 De twee andere commando's die je niet eerder hebt gezien
195 zijn @code{\layout @{ @}} en @code{\midi @{@}}. Als deze
196 gebruikt worden als hierboven laten ze LilyPond
197 respectievelijk geprinte- en MIDI-uitvoer genereren. Een
198 volledige beschrijving van deze commando's is te vinden in
199 de Notatiehandleiding -- @ruser{Score layout}, en
200 @ruser{Creating MIDI files}.
202 @cindex partituren, verscheidene
203 @cindex boek blok, impliciet
204 @cindex impliciet boek blok
208 Je kunt meer dan een @code{\score}-blok gebruiken. Elk
209 wordt behandeld als een afzonderlijke partituur en ze worden
210 allemaal samengevoegd in een enkel uitvoerbestand. Een
211 @code{\book}-commando is niet nodig -- die wordt impliciet
212 aangemaakt. Echter, als je afzonderlijke uitvoerbestanden
213 vanuit een @code{.ly}-bestand wil maken, dan moet het
214 @code{\book}-commando worden gebruikt om de verschillende
215 secties aan te geven: elk @code{\book}-blok produceert
216 een apart uitvoerbestand.
220 Elk @code{\book}-blok geeft een apart uitvoerbestand (bijv.,
221 een PDF-bestand). Als je er geen expliciet toevoegt, stopt
222 LilyPond je gehele invoercode impliciet in een
225 Elk @code{\score}-blok is een apart brok muziek binnen een
228 @cindex opmaakblok, effect van locatie
230 Elk @code{\layout}-blok beïnvloedt het @code{\score}- of
231 @code{\book}-blok waarin het voorkomt -- d.w.z., een
232 @code{\layout}-blok binnen een @code{\score}-blok heeft
233 uitsluitend invloed op dat @code{\score}-blok, maar een
234 @code{\layout}-blok buiten een @code{\score}-blok (en dus
235 binnen een @code{\book}-blok, expliciet danwel impliciet)
236 beïnvloedt elke @code{\score} in dat @code{\book}.
238 Voor details zie @ruser{Multiple scores in a book}.
242 Een andere manier van afkorten is het gebruik van
243 variabelen, zoals getoond in @ref{Stukken organiseren met
244 variabelen}. Alle sjablonen gebruiken dat:
247 melodie = \relative c' @{
256 Als LilyPond naar dit bestand kijkt, neemt het de waarde van
257 @code{melodie} (alles na het isgelijkteken) en voegt die in
258 zodra ergens @code{\melody} staat. De naam van de variable
259 heeft verder geen speciale betekenis -- het kan net zo goed
260 @code{melodie}, @code{globaal}, @code{TijdSleutel},
261 @code{pianorechterhand}, of @code{blablabla} zijn. Voor
262 meer details, zie @ref{Saving typing with variables and
263 functions}. Herrinner je dat je vrijwel elke naam kunt
264 gebruiken die je wilt, zolang die maar bestaat uit letters
265 en het niet de naam is van een LilyPond-commando. De
266 precieze beperkingen van variabelenamen staan beschreven in
267 @ruser{File structure}.
271 Voor een volledige definitie van het invoerformaat, zie
272 @ruser{File structure}.
275 @node Score is a (single) compound musical expression
277 @subsection Score is a (single) compound musical expression
282 @cindex contents of a score block
283 @cindex score block, contents of
284 @cindex compound music expression
285 @cindex music expression, compound
287 We saw the general organization of LilyPond input files in the
288 previous section, @ref{Introduction to the LilyPond file structure}.
289 But we seemed to skip over the most important part: how do we figure
290 out what to write after @code{\score}?
292 We didn't skip over it at all. The big mystery is simply that
293 there @emph{is} no mystery. This line explains it all:
296 @emph{A @code{\score} block must begin with a compound music expression.}
300 To understand what is meant by a music expression and a compound
301 music expression, you may find it useful to review the tutorial,
302 @ref{Music expressions explained}. In that section, we saw how to
303 build big music expressions from small pieces -- we started from
304 notes, then chords, etc. Now we're going to start from a big
305 music expression and work our way down. For simplicity, we'll use
306 just a singer and piano in our example. We don't need a
307 @code{StaffGroup} for this ensemble, which simply groups a number
308 of staves together with a bracket at the left, but we do need
309 staves for a singer and a piano, though.
314 \new Staff = "singer" <<
316 \new PianoStaff = "piano" <<
323 Here we have given names to the staves -- @qq{singer} and
324 @qq{piano}. This is not essential here, but it is a useful habit
325 to cultivate so that you can see at a glance what each stave is
328 Remember that we use @code{<< ... >>} instead of @code{@{ ... @}} to
329 show simultaneous music. This causes the vocal part and piano part
330 to appear one above the other in the score. The @code{<< ... >>}
331 construct would not be necessary for the Singer staff in the example
332 above if it were going to contain only one sequential music
333 expression, but @code{<< ... >>} rather than braces is necessary if
334 the music in the Staff is to contain two or more simultaneous
335 expressions, e.g. two simultaneous Voices, or a Voice with lyrics.
336 We're going to have a voice with lyrics, so angle brackets are
337 required. We'll add some real music later; for now let's just put
338 in some dummy notes and lyrics. If you've forgotten how to add lyrics
339 you may wish to review @code{\addlyrics} in @ref{Setting simple songs}.
341 @lilypond[verbatim,quote,ragged-right]
344 \new Staff = "singer" <<
345 \new Voice = "vocal" { c'1 }
348 \new PianoStaff = "piano" <<
349 \new Staff = "upper" { c'1 }
350 \new Staff = "lower" { c'1 }
357 Now we have a lot more details. We have the singer's staff: it
358 contains a @code{Voice} (in LilyPond, this term refers to a set of
359 notes, not necessarily vocal notes -- for example, a violin
360 generally plays one voice) and some lyrics. We also have a piano
361 staff: it contains an upper staff (right hand) and a lower staff
362 (left hand), although the lower staff has yet to be given a bass
365 At this stage, we could start filling in notes. Inside the curly
366 braces next to @code{\new Voice = "vocal"}, we could start writing
374 But if we did that, the @code{\score} section would get pretty
375 long, and it would be harder to understand what was happening. So
376 let's use variables instead. These were introduced at the end
377 of the previous section, remember? To ensure the contents of the
378 @code{text} variable are interpreted as lyrics we preface them with
379 @code{\lyricmode}. Like @code{\addlyrics}, this switches the input
380 mode to lyrics. Without that, LilyPond would try to interpret the
381 contents as notes, which would generate errors. (Several other
382 input modes are available, see @ruser{Input modes}.)
384 So, adding a few notes and a bass clef for the left hand, we now
385 have a piece of real music:
387 @lilypond[verbatim,quote,ragged-right]
388 melody = \relative c'' { r4 d8\noBeam g, c4 r }
389 text = \lyricmode { And God said, }
390 upper = \relative c'' { <g d g,>2~ <g d g,> }
391 lower = \relative c { b2 e2 }
395 \new Staff = "singer" <<
396 \new Voice = "vocal" { \melody }
399 \new PianoStaff = "piano" <<
400 \new Staff = "upper" { \upper }
401 \new Staff = "lower" {
411 When writing (or reading) a @code{\score} section, just take it
412 slowly and carefully. Start with the outer level, then work on
413 each smaller level. It also really helps to be strict with
414 indentation -- make sure that each item on the same level starts
415 on the same horizontal position in your text editor.
419 Notation Reference: @ruser{Structure of a score}.
422 @node Nesting music expressions
424 @subsection Nesting music expressions
426 @cindex staves, temporary
427 @cindex temporary staves
430 It is not essential to declare all staves at the beginning; they may
431 be introduced temporarily at any point. This is particularly useful
432 for creating ossia sections -- see @rglos{ossia}. Here is a simple
433 example showing how to introduce a new staff temporarily for the
434 duration of three notes:
436 @lilypond[verbatim,quote,ragged-right]
453 Note that the size of the clef is the same as a clef printed
454 following a clef change -- slightly smaller than the clef
455 at the beginning of the line. This is usual for clefs printed
456 in the middle of a line.
458 @cindex staff, positioning
460 The ossia section may be placed above the staff
463 @lilypond[verbatim,quote,ragged-right]
464 \new Staff = "main" {
471 alignAboveContext = #"main" }
479 This example uses @code{\with}, which will be explained more
480 fully later. It is a means of modifying the default behavior
481 of a single Staff. Here it says that the new staff should be
482 placed above the staff called @qq{main} instead of the default
483 position which is below.
487 Ossia are often written without clef and without
488 time signature and are usually in a smaller font.
489 These require further commands which
490 have not yet been introduced. See @ref{Size of objects},
491 and @ruser{Ossia staves}.
494 @node On the un-nestedness of brackets and ties
496 @subsection On the un-nestedness of brackets and ties
498 @cindex brackets, nesting
499 @cindex bracket types
500 @cindex brackets, enclosing vs. marking
502 You have already met a number of different types of bracket and
503 bracket-like constructs in writing the input file to LilyPond.
504 These obey different rules which can be confusing at first.
505 Let's first review the different types of brackets and bracket-like
508 @c attempt to force this onto a new page
510 @multitable @columnfractions .3 .7
511 @headitem Bracket Type
513 @item @code{@{ .. @}}
514 @tab Encloses a sequential segment of music
516 @tab Encloses the notes of a chord
517 @item @code{<< .. >>}
518 @tab Encloses simultaneous music expressions
520 @tab Marks the start and end of a slur
521 @item @code{\( .. \)}
522 @tab Marks the start and end of a phrasing slur
524 @tab Marks the start and end of a manual beam
527 To these we should add other constructs which generate lines
528 between or across notes: ties (marked by a tilde, @code{~}),
529 tuplets written as @code{\times x/y @{..@}}, and grace notes
530 written as @code{\grace@{..@}}.
532 Outside LilyPond, the conventional use of brackets requires the
533 different types to be properly nested, like this, @code{<< [ @{ ( .. )
534 @} ] >>}, with the closing brackets being encountered in exactly the
535 opposite order to the opening brackets. This @strong{is} a
536 requirement for the three types of bracket described by the word
537 @q{Encloses} in the table above -- they must nest properly. However,
538 the remaining bracket-like constructs, described with the word
539 @q{Marks} in the table above together with ties and tuplets, do
540 @strong{not} have to nest properly with any of the brackets or
541 bracket-like constructs. In fact, these are not brackets in
542 the sense that they enclose something -- they are simply markers to
543 indicate where something starts and ends.
545 So, for example, a phrasing slur can start before a manually
546 inserted beam and end before the end of the beam -- not very
547 musical, perhaps, but possible:
549 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
550 { g8\( a b[ c b\) a] }
553 In general, different kinds of brackets, bracket-like constructs,
554 and those implied by tuplets, ties and grace notes, may be mixed
555 freely. This example shows a beam extending into a tuplet (line 1),
556 a slur extending into a tuplet (line 2), a beam and a slur
557 extending into a tuplet, a tie crossing two tuplets, and a
558 phrasing slur extending out of a tuplet (lines 3 and 4).
560 @lilypond[quote,verbatim,fragment,ragged-right]
562 r16[ g16 \times 2/3 {r16 e'8] }
563 g16( a \times 2/3 {b d) e' }
564 g8[( a \times 2/3 {b d') e'~]}
565 \times 4/5 {e'32\( a b d' e'} a'4.\)
570 @node Voices contain music
572 @section Voices contain music
574 Singers need voices to sing, and so does LilyPond.
575 The actual music for all instruments in a score
576 is contained in Voices -- the most fundamental
577 of all LilyPond's concepts.
580 * I'm hearing Voices::
581 * Explicitly instantiating voices::
582 * Voices and vocals::
585 @node I'm hearing Voices
587 @subsection I'm hearing Voices
591 @cindex multiple voices
592 @cindex voices, multiple
593 @cindex Voice context
594 @cindex context, Voice
595 @cindex simultaneous music
596 @cindex music, simultaneous
597 @cindex concurrent music
598 @cindex music, concurrent
599 @cindex voices vs. chords
600 @cindex chords vs. voices
602 The lowest, most fundamental or innermost layers in a LilyPond
603 score are called @q{Voice contexts} or just @q{Voices} for short.
604 Voices are sometimes called @q{layers} in other notation
607 In fact, a Voice layer or context is the only one which can contain
608 music. If a Voice context is not explicitly declared one is created
609 automatically, as we saw at the beginning of this chapter. Some
610 instruments such as an Oboe can play only one note at a time. Music
611 written for such instruments is monophonic and requires just a single
612 voice. Instruments which can play more than one note at a time like
613 the piano will often require multiple voices to encode the different
614 concurrent notes and rhythms they are capable of playing.
616 A single voice can contain many notes in a chord, of course,
617 so when exactly are multiple voices needed? Look first at
618 this example of four chords:
620 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
622 <d g>4 <d fis> <d a'> <d g>
625 This can be expressed using just the single angle bracket chord
626 symbols, @code{< ... >}, and for this just a single voice is
627 needed. But suppose the F-sharp were actually an eighth-note
628 followed by an eighth-note G, a passing note on the way to the A?
629 Now we have two notes which start at the same time but have
630 different durations: the quarter-note D and the eighth-note
631 F-sharp. How are these to be coded? They cannot be written as
632 a chord because all the notes in a chord must have the same
633 duration. And they cannot be written as two sequential notes
634 as they need to start at the same time. This is when two
637 Let us see how this is done in LilyPond input syntax.
642 The easiest way to enter fragments with more than one voice on a
643 staff is to enter each voice as a sequence (with @code{@{...@}}),
644 and combine them simultaneously with angle brackets, @code{<<...>>}.
645 The fragments must also be separated with double backward slashes,
646 @code{\\}, to place them in separate voices. Without these, the
647 notes would be entered into a single voice, which would usually
648 cause errors. This technique is particularly suited to pieces of
649 music which are largely monophonic with occasional short sections
652 Here's how we split the chords above into two voices and add both
653 the passing note and a slur:
655 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
657 % Voice "1" Voice "2"
658 << { g4 fis8( g) a4 g } \\ { d4 d d d } >>
661 Notice how the stems of the second voice now point down.
663 Here's another simple example:
665 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
667 % Voice "1" Voice "2"
668 << { r4 g g4. a8 } \\ { d,2 d4 g } >>
669 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >>
670 << { a2. r4 } \\ { fis2. s4 } >>
673 It is not necessary to use a separate @code{<< \\ >>} construct
674 for each bar. For music with few notes in each bar this layout
675 can help the legibility of the code, but if there are many
676 notes in each bar it may be better to split out each voice
677 separately, like this:
679 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
695 @cindex voices, naming
696 @cindex voices crossing brackets
697 @cindex slurs crossing brackets
698 @cindex ties crossing brackest
700 This example has just two voices, but the same construct may be
701 used to encode three or more voices by adding more back-slash
704 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
705 In each of these contexts, the vertical direction of slurs,
706 stems, ties, dynamics etc., is set appropriately.
708 @lilypond[quote,verbatim,fragment]
709 \new Staff \relative c' {
712 % Voice "1" Voice "2" Voice "3"
713 << { g4 f e } \\ { r8 e4 d c8~ } >>
714 << { d2 e2 } \\ { c8 b16 a b8 g~ g2 } \\ { s4 b4 c2 } >>
718 These voices are all separate from the main voice that contains
719 the notes just outside the @code{<< .. >>} construct. Let's call
720 this the @emph{simultaneous construct}. Slurs and ties may only
721 connect notes within the same voice, so slurs and ties cannot go
722 into or out of a simultaneous construct. Conversely,
723 parallel voices from separate simultaneous constructs on the same
724 staff are the same voice. Other voice-related properties also
725 carry across simultaneous constructs. Here is the same example,
726 with different colors and note heads for each voice. Note that
727 changes in one voice do not affect other voices, but they do
728 persist in the same voice later. Note also that tied notes may be
729 split across the same voices in two constructs, shown here in the
732 @lilypond[quote,verbatim]
733 \new Staff \relative c' {
752 { c8 b16 a b8 g ~ g2 }
762 @funindex \voiceOneStyle
763 @funindex \voiceTwoStyle
764 @funindex \voiceThreeStyle
765 @funindex \voiceFourStyle
766 @funindex \voiceNeutralStyle
768 The commands @code{\voiceXXXStyle} are mainly intended for use in
769 educational documents such as this one. They modify the color
770 of the note head, the stem and the beams, and the style of the
771 note head, so that the voices may be easily distinguished.
772 Voice one is set to red diamonds, voice two to blue triangles,
773 voice three to green crossed circles, and voice four (not used
774 here) to magenta crosses; @code{\voiceNeutralStyle} (also not
775 used here) reverts the style back to the default.
776 We shall see later how commands like these may be created by the
778 See @ref{Visibility and color of objects} and
779 @ref{Using variables for tweaks}.
781 @cindex polyphony and relative note entry
782 @cindex relative note entry and polyphony
784 Polyphony does not change the relationship of notes within a
785 @code{\relative @{ @}} block. Each note is still calculated
786 relative to the note immediately preceding it, or to the first
787 note of the preceding chord. So in
790 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
794 @code{noteB} is relative to @code{noteA} @*
795 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
796 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
798 @code{noteE} is relative to @code{noteD}, not @code{noteA}.
800 An alternative way, which may be clearer if the notes in the
801 voices are widely separated, is to place a @code{\relative}
802 command at the start of each voice:
805 \relative c' @{ noteA ... @}
807 \relative c'' @{ < noteB noteC > ... @}
809 \relative g' @{ noteD ... @}
811 \relative c' @{ noteE ... @}
814 Let us finally analyze the voices in a more complex piece of music.
815 Here are the notes from the first two bars of the second of Chopin's
816 Deux Nocturnes, Op 32. This example will be used at later stages in
817 this and the next chapter to illustrate several techniques for
818 producing notation, so please ignore for now anything in the
819 underlying code which looks mysterious and concentrate just on the
820 music and the voices -- the complications will all be explained in
823 @c The following should appear as music without code
824 @lilypond[quote,ragged-right]
825 \new Staff \relative c'' {
834 % Ignore these for now - they are explained in Ch 4
835 \once \override NoteColumn #'force-hshift = #0
837 \once \override NoteColumn #'force-hshift = #0.5
845 The direction of the stems is often used to indicate the continuity of
846 two simultaneous melodic lines. Here the stems of the highest notes
847 are all pointing up and the stems of the lower notes are all pointing
848 down. This is the first indication that more than one voice is
851 But the real need for multiple voices arises when notes
852 which start at the same time have different durations.
853 Look at the notes which start at beat three in the first
854 bar. The A-flat is a dotted quarter note, the F is a
855 quarter note and the D-flat is a half note. These
856 cannot be written as a chord as all the notes in a chord
857 must have the same duration. Neither can they be written
858 as sequential notes, as they must start at the same time.
859 This section of the bar requires three voices, and the
860 normal practice would be to write the whole bar as three
861 voices, as shown below, where we have used different note heads
862 and colors for the three voices. Again, the code behind this
863 example will be explained later, so ignore anything you do
866 @c The following should appear as music without code
867 @c The three voice styles should be defined in -init
868 @lilypond[quote,ragged-right]
869 \new Staff \relative c'' {
880 \\ % No Voice three (we want stems down)
883 % Ignore these for now - they are explained in Ch 4
884 \once \override NoteColumn #'force-hshift = #0
886 \once \override NoteColumn #'force-hshift = #0.5
895 Let us try to encode this music from scratch. As we
896 shall see, this encounters some difficulties. We begin as
897 we have learnt, using the @code{<< \\ >>} construct to
898 enter the music of the first bar in three voices:
900 @lilypond[quote,verbatim,fragment,ragged-right]
901 \new Staff \relative c'' {
904 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
911 @cindex voices and stem directions
912 @cindex stem directions and voices
915 The stem directions are automatically assigned with the
916 odd-numbered voices taking upward stems and the even-numbered
917 voices downward ones. The stems for voices 1 and 2 are right,
918 but the stems in voice 3 should go down in this particular piece
919 of music. We can correct this by skipping voice three
920 and placing the music in voice four. This is done by simply
921 adding another pair of @code{\\}.
923 @lilypond[quote,verbatim,fragment,ragged-right]
924 \new Staff \relative c'' {
930 \\ % Omit Voice three
939 We see that this fixes the stem direction, but exposes a problem
940 sometimes encountered with multiple voices -- the stems of the notes
941 in one voice can collide with the note heads in other voices. In
942 laying out the notes, LilyPond allows the notes or chords from two
943 voices to occupy the same vertical note column provided the stems are
944 in opposite directions, but the notes from the third and fourth voices
945 are displaced, if necessary, to avoid the note heads colliding. This
946 usually works well, but in this example the notes of the lowest voice
947 are clearly not well placed by default. LilyPond provides several ways
948 to adjust the horizontal placing of notes. We are not quite ready yet
949 to see how to correct this, so we shall leave this problem until a
950 later section --- see the @code{force-hshift} property in @ref{Fixing
951 overlapping notation}.
955 Notation Reference: @ruser{Multiple voices}.
958 @node Explicitly instantiating voices
960 @subsection Explicitly instantiating voices
966 @funindex \voiceThree
973 @cindex voice contexts, creating
975 Voice contexts can also be created manually
976 inside a @code{<< >>} block to create polyphonic music, using
977 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
978 directions of stems, slurs, etc. In longer scores this method
979 is clearer, as it permits the voices to be separated and to be
980 given more descriptive names.
982 Specifically, the construct @code{<< \\ >>} which we used in
983 the previous section:
988 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
998 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
999 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
1003 Both of the above would produce
1005 @c The following example should not display the code
1006 @lilypond[ragged-right,quote]
1008 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
1009 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
1013 @cindex voices, reverting to single
1014 @cindex reverting to a single voice
1016 The @code{\voiceXXX} commands set the direction of stems, slurs,
1017 ties, articulations, text annotations, augmentation dots of dotted
1018 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
1019 make these objects point upwards, while @code{\voiceTwo} and
1020 @code{\voiceFour} make them point downwards. These commands also
1021 generate a horizontal shift for each voice when this is required
1022 to avoid clashes of note heads. The command @code{\oneVoice}
1023 reverts the settings back to the normal values for a single voice.
1025 Let us see in some simple examples exactly what effect
1026 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
1027 markup, ties, slurs, and dynamics:
1029 @lilypond[quote,ragged-right,verbatim]
1031 % Default behavior or behavior after \oneVoice
1032 c d8~ d e4( f g a) b-> c
1036 @lilypond[quote,ragged-right,verbatim]
1039 c d8~ d e4( f g a) b-> c
1041 c, d8~ d e4( f g a) b-> c
1045 @lilypond[quote,ragged-right,verbatim]
1048 c d8~ d e4( f g a) b-> c
1050 c, d8~ d e4( f g a) b-> c
1054 Now let's look at three different ways to notate the same passage
1055 of polyphonic music, each of which is advantageous in different
1056 circumstances, using the example from the previous section.
1058 An expression that appears directly inside a @code{<< >>} belongs
1059 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
1060 construct). This is useful when extra voices appear while the
1061 main voice is playing. Here is a more correct rendition of our
1062 example. The red diamond-shaped notes
1063 demonstrate that the main melody is now in a single voice context,
1064 permitting a phrasing slur to be drawn over them.
1066 @lilypond[quote,ragged-right,verbatim]
1067 \new Staff \relative c' {
1069 % The following notes are monophonic
1071 % Start simultaneous section of three voices
1073 % Continue the main voice in parallel
1074 { g4 f e | d2 e2) | }
1075 % Initiate second voice
1077 % Set stems, etc., down
1079 r8 e4 d c8~ | c8 b16 a b8 g~ g2 |
1081 % Initiate third voice
1083 % Set stems, etc, up
1091 @cindex nesting music expressions
1092 @cindex nesting simultaneous constructs
1093 @cindex nesting voices
1094 @cindex voices, temporary
1095 @cindex voices, nesting
1097 More deeply nested polyphony constructs are possible, and if a
1098 voice appears only briefly this might be a more natural way to
1101 @lilypond[quote,ragged-right,verbatim]
1102 \new Staff \relative c' {
1105 { g4 f e | d2 e2) | }
1110 { c8 b16 a b8 g~ g2 }
1121 @cindex spacing notes
1123 This method of nesting new voices briefly is useful
1124 when only small sections of the music
1125 are polyphonic, but when the whole staff is largely polyphonic
1126 it can be clearer to use multiple voices throughout, using
1127 spacing notes to step over sections where the voice is silent,
1130 @lilypond[quote,ragged-right,verbatim]
1131 \new Staff \relative c' <<
1132 % Initiate first voice
1135 c16^( d e f g4 f e | d2 e2) |
1137 % Initiate second voice
1139 % Set stems, etc, down
1141 s4 r8 e4 d c8~ | c8 b16 a b8 g~ g2 |
1143 % Initiate third voice
1145 % Set stems, etc, up
1152 @subsubheading Note columns
1155 @cindex note collisions
1156 @cindex collisions, notes
1157 @cindex shift commands
1164 @funindex \shiftOnnn
1167 Closely spaced notes in a chord, or notes occurring at the same
1168 time in different voices, are arranged in two, occasionally more,
1169 columns to prevent the note heads overlapping. These are called
1170 note columns. There are separate columns for each voice, and
1171 the currently specified voice-dependent shift is applied to the
1172 note column if there would otherwise be a collision. This can
1173 be seen in the example above. In bar 2 the C in voice two is
1174 shifted to the right relative to the D in voice one, and in the
1175 final chord the C in voice three is also shifted to the right
1176 relative to the other notes.
1178 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1179 @code{\shiftOff} commands specify the degree to which notes and
1180 chords of the voice should be shifted if a collision
1181 would otherwise occur. By default, the outer voices (normally
1182 voices one and two) have @code{\shiftOff} specified, while the
1183 inner voices (three and four) have @code{\shiftOn} specified.
1184 When a shift is applied, voices one and three are shifted to
1185 the right and voices two and four to the left.
1187 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1188 levels which may be specified temporarily to resolve collisions
1189 in complex situations -- see @ref{Real music example}.
1191 A note column can contain just one note (or chord) from a voice
1192 with stems up and one note (or chord) from a voice with stems
1193 down. If notes from two voices which have their stems in the
1194 same direction are placed at the same position and both voices
1195 have no shift or the same shift specified, the error message
1196 @qq{Too many clashing note columns} will be produced.
1200 Notation Reference: @ruser{Multiple voices}.
1203 @node Voices and vocals
1205 @subsection Voices and vocals
1207 Vocal music presents a special difficulty: we need to combine two
1208 expressions -- notes and lyrics.
1210 @funindex \new Lyrics
1214 @cindex Lyrics context, creating
1215 @cindex lyrics, linking to voice
1217 You have already seen the @code{\addlyrics@{@}} command, which
1218 handles simple scores well. However, this technique is
1219 quite limited. For more complex music, you must introduce the
1220 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1222 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1223 name assigned to the Voice.
1225 @lilypond[quote,verbatim,fragment]
1227 \new Voice = "one" \relative c'' {
1230 c4 b8. a16 g4. f8 e4 d c2
1232 \new Lyrics \lyricsto "one" {
1233 No more let sins and sor -- rows grow.
1238 Note that the lyrics must be linked to a @code{Voice} context,
1239 @emph{not} a @code{Staff} context. This is a case where it is
1240 necessary to create @code{Staff} and @code{Voice} contexts
1243 @cindex lyrics and beaming
1244 @cindex beaming and lyrics
1245 @funindex \autoBeamOff
1246 @funindex autoBeamOff
1248 The automatic beaming which LilyPond uses by default works well
1249 for instrumental music, but not so well for music with lyrics,
1250 where beaming is either not required at all or is used to indicate
1251 melismata in the lyrics. In the example above we use the command
1252 @code{\autoBeamOff} to turn off the automatic beaming.
1254 @funindex \new ChoirStaff
1255 @funindex ChoirStaff
1256 @funindex \lyricmode
1258 @cindex vocal score structure
1261 Let us reuse the earlier example from Judas Maccabæus to
1262 illustrate this more flexible technique. We first recast
1263 it to use variables so the music and lyrics can be separated
1264 from the staff structure. We also introduce a ChoirStaff
1265 bracket. The lyrics themselves must be introduced with
1266 @code{\lyricmode} to ensure they are interpreted as lyrics
1269 @lilypond[quote,verbatim]
1270 global = { \time 6/8 \partial 8 \key f \major}
1271 SopOneMusic = \relative c'' {
1272 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 | }
1273 SopTwoMusic = \relative c' {
1274 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' | }
1275 SopOneLyrics = \lyricmode {
1276 Let | flee -- cy flocks the | hills a -- dorn, __ | }
1277 SopTwoLyrics = \lyricmode {
1278 Let | flee -- cy flocks the | hills a -- dorn, | }
1283 \new Voice = "SopOne" {
1287 \new Lyrics \lyricsto "SopOne" {
1292 \new Voice = "SopTwo" {
1296 \new Lyrics \lyricsto "SopTwo" {
1304 This is the basic structure of all vocal scores. More staves may be
1305 added as required, more voices may be added to the staves, more verses
1306 may be added to the lyrics, and the variables containing the music can
1307 easily be placed in separate files should they become too long.
1309 @cindex hymn structure
1310 @cindex SATB structure
1311 @cindex vocal scores with multiple verses
1312 @cindex multiple vocal verses
1313 @cindex verses, multiple vocal
1315 Here is an example of the first line of a hymn with four
1316 verses, set for SATB. In this case the words for all four
1317 parts are the same. Note how we use variables to separate the
1318 music notation and words from the staff structure. See too
1319 how a variable, which we have chosen to call @q{TimeKey}, is used
1320 to hold several commands for use within the two staves. In other
1321 examples this is often called @q{global}.
1323 @lilypond[quote,verbatim]
1324 TimeKey = { \time 4/4 \partial 4 \key c \major}
1325 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g | }
1326 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e | }
1327 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 | }
1328 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 | }
1329 VerseOne = \lyricmode {
1330 E -- | ter -- nal fa -- ther, | strong to save, | }
1331 VerseTwo = \lyricmode {
1332 O | Christ, whose voice the | wa -- ters heard, | }
1333 VerseThree = \lyricmode {
1334 O | Ho -- ly Spi -- rit, | who didst brood | }
1335 VerseFour = \lyricmode {
1336 O | Tri -- ni -- ty of | love and pow'r | }
1342 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1343 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1344 \new Lyrics \lyricsto "Sop" { \VerseOne }
1345 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1346 \new Lyrics \lyricsto "Sop" { \VerseThree }
1347 \new Lyrics \lyricsto "Sop" { \VerseFour }
1351 \new Voice = "Tenor" { \voiceOne \TimeKey \TenorMusic }
1352 \new Voice = "Bass" { \voiceTwo \BassMusic }
1358 @cindex verse and refrain
1360 We end with an example to show how we might code a solo verse which
1361 continues into a two-part refrain in two staves. The positioning
1362 of the sequential and simultaneous sections to achieve this within
1363 a single score is quite tricky, so follow the explanation carefully!
1365 Let's start with a score block containing a @code{ChoirStaff}, as
1366 we would like the brace to appear at the start of the chorus.
1367 Normally you would need angle brackets after @code{\new ChoirStaff}
1368 to bring in all the staves in parallel, but here we want to
1369 defer the parallelism during the solo so we use braces, although
1370 angle brackets here wouldn't hurt. Inside the @code{ChoirStaff} we
1371 want first the staff which will contain the verse. This must
1372 contain notes and lyrics in parallel, so here we need angle
1373 brackets around the @code{\new Voice} and @code{\new Lyrics} to
1374 start them at the same time:
1376 @lilypond[quote,verbatim,ragged-right]
1377 versenotes = \relative c'' {
1383 versewords = \lyricmode {
1384 One two three four five six
1389 \new Voice = "verse" {
1392 \new Lyrics \lyricsto verse {
1400 That gives the verse line.
1402 Now we want to continue with refrainA on the same staff while a
1403 second staff is introduced in parallel with it for refrainB, so
1404 this is a parallel section which must be positioned immediately
1405 following the @code{\break} in the verse Voice. Yes, @emph{within}
1406 the verse Voice! Here's that parallel section. More staves
1407 could be introduced here in the same way.
1412 \new Lyrics \lyricsto verse @{
1416 \new Voice = "refrainB" @{
1419 \new Lyrics \lyricsto "refrainB" @{
1426 Here's the final result with two staves in the chorus showing
1427 how the parallel section is positioned within the verse Voice:
1429 @lilypond[quote,verbatim, ragged-right]
1430 versenotes = \relative c'' {
1436 refrainnotesA = \relative c'' {
1440 refrainnotesB = \relative c {
1445 versewords = \lyricmode {
1446 One two three four five six
1448 refrainwordsA = \lyricmode {
1451 refrainwordsB = \lyricmode {
1457 \new Voice = "verse" {
1461 \new Lyrics \lyricsto "verse" {
1465 \new Voice = "refrainB" {
1468 \new Lyrics \lyricsto "refrainB" {
1474 \new Lyrics \lyricsto "verse" {
1482 @cindex book, example of using
1486 However, although this is an interesting and useful exercise to
1487 help you to understand how sequential and simultaneous blocks work,
1488 in practice one would perhaps choose to code this as two
1489 @code{\score} blocks within an implicit @code{\book} block, as
1492 @lilypond[quote,verbatim,ragged-right]
1493 versenotes = \relative c'' {
1499 refrainnotesA = \relative c'' {
1503 refrainnotesB = \relative c {
1508 versewords = \lyricmode {
1509 One two three four five six
1511 refrainwordsA = \lyricmode {
1514 refrainwordsB = \lyricmode {
1519 \new Voice = "verse" {
1522 \new Lyrics \lyricsto "verse" {
1531 \new Voice = "refrainA" {
1534 \new Lyrics \lyricsto "refrainA" {
1539 \new Voice = "refrainB" {
1542 \new Lyrics \lyricsto "refrainB" {
1552 Notation Reference: @ruser{Vocal music}.
1555 @node Contexts and engravers
1557 @section Contexts and engravers
1559 Contexts and engravers have been mentioned informally
1560 in earlier sections; we now must look at
1561 these concepts in more detail, as they are important
1562 in the fine-tuning of LilyPond output.
1566 * Contexts explained::
1567 * Creating contexts::
1568 * Engravers explained::
1569 * Modifying context properties::
1570 * Adding and removing engravers::
1573 @node Contexts explained
1575 @subsection Contexts explained
1577 @cindex contexts explained
1579 When music is printed, many notational elements which do not
1580 appear explicitly in the input file must be added to the
1581 output. For example, compare the input and output of the
1584 @lilypond[quote,verbatim,relative=2,fragment]
1588 The input is rather sparse, but in the output, bar lines,
1589 accidentals, clef, and time signature have been added. When
1590 LilyPond @emph{interprets} the input the musical information
1591 is parsed from left to right, similar to the way a performer
1592 reads the score. While reading the input, the program remembers
1593 where measure boundaries are, and which pitches require explicit
1594 accidentals. This information must be held on several levels.
1595 For example, an accidental affects only a single staff, while
1596 a bar line must be synchronized across the entire score.
1598 Within LilyPond, these rules and bits of information are grouped in
1599 @emph{Contexts}. We have already introduced the @code{Voice} context.
1600 Others are the @code{Staff} and @code{Score} contexts. Contexts are
1601 hierarchical to reflect the hierarchical nature of a musical score.
1602 For example: a @code{Staff} context can contain many @code{Voice}
1603 contexts, and a @code{Score} context can contain many @code{Staff}
1607 @sourceimage{context-example,5cm,,}
1610 Each context has the responsibility for enforcing some notation rules,
1611 creating some notation objects and maintaining the associated
1612 properties. For example, the @code{Voice} context may introduce an
1613 accidental and then the @code{Staff} context maintains the rule to
1614 show or suppress the accidental for the remainder of the measure.
1616 As another example, the synchronization of bar lines is, by default,
1617 handled in the @code{Score} context.
1618 However, in some music we may not want the bar lines to be
1619 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1620 In such cases, we must modify the default settings of the
1621 @code{Score} and @code{Staff} contexts.
1623 For very simple scores, contexts are created implicitly, and you need
1624 not be aware of them. For larger pieces, such as anything with more
1625 than one staff, they must be
1626 created explicitly to make sure that you get as many staves as you
1627 need, and that they are in the correct order. For typesetting pieces
1628 with specialized notation, it is usual to modify existing, or
1629 even to define totally new, contexts.
1631 In addition to the @code{Score,} @code{Staff} and
1632 @code{Voice} contexts there are contexts which fit between
1633 the score and staff levels to control staff groups, such as the
1634 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1635 are also alternative staff and voice contexts, and contexts for
1636 lyrics, percussion, fret boards, figured bass, etc.
1638 The names of all context types are formed from one or more
1639 words, each word being capitalized and joined immediately to the
1640 preceding word with no hyphen or underscore, e.g.,
1641 @code{GregorianTranscriptionStaff}.
1645 Notation Reference: @ruser{Contexts explained}.
1648 @node Creating contexts
1650 @subsection Creating contexts
1654 @cindex new contexts
1655 @cindex creating contexts
1656 @cindex contexts, creating
1658 In an input file a score block, introduced with a @code{\score}
1659 command, contains a single music expression and an associated
1660 output definition (either a @code{\layout} or a @code{\midi} block).
1661 The @code{Score} context is usually left to be created automatically
1662 when the interpretation of that music expression starts.
1664 For scores with only one voice and one staff, the @code{Voice} and
1665 @code{Staff} contexts may also be left to be created automatically,
1666 but for more complex scores it is necessary to create them by hand.
1667 The simplest command that does this is @code{\new}. It is prepended
1668 to a music expression, for example
1671 \new @var{type} @var{music-expression}
1675 where @var{type} is a context name (like @code{Staff} or
1676 @code{Voice}). This command creates a new context, and starts
1677 interpreting the @var{music-expression} within that context.
1679 (Note that a @code{\new Score} command is not normally required,
1680 as the essential top-level @code{Score} context is created
1681 automatically when the music expression within the @code{\score}
1682 block is interpreted. The only reason for creating a @code{Score}
1683 context explicitly using @code{\new Score} is to introduce a
1684 @code{\with} block in which one or more score-wide default values
1685 of context properties may be specified. Information on using
1686 @code{\with} blocks can be found under the heading
1687 @qq{Setting context properties with @code{\\with} } in
1688 @ref{Modifying context properties}.)
1690 You have seen many practical examples which created new
1691 @code{Staff} and @code{Voice} contexts in earlier sections, but
1692 to remind you how these commands are used in practice, here's an
1693 annotated real-music example:
1695 @lilypond[quote,verbatim,ragged-right]
1696 \score { % start of single compound music expression
1697 << % start of simultaneous staves section
1699 \new Staff { % create RH staff
1702 \new Voice { % create voice for RH notes
1703 \relative c'' { % start of RH notes
1709 \new Staff << % create LH staff; needs two simultaneous voices
1712 \new Voice { % create LH voice one
1714 \relative g { % start of LH voice one notes
1715 g8 <bes d> ees, <g c>
1716 g8 <bes d> ees, <g c>
1717 } % end of LH voice one notes
1718 } % end of LH voice one
1719 \new Voice { % create LH voice two
1721 \relative g { % start of LH voice two notes
1724 } % end of LH voice two notes
1725 } % end of LH voice two
1726 >> % end of LH staff
1727 >> % end of simultaneous staves section
1728 } % end of single compound music expression
1731 (Note how all the statements which open a block with either a
1732 curly bracket, @code{@{}, or double angle brackets, @code{<<},
1733 are indented by two further spaces, and the corresponding
1734 closing bracket is indented by exactly the same amount. While
1735 this is not required, following this practice will greatly
1736 reduce the number of @q{unmatched bracket} errors, and is
1737 strongly recommended. It enables the structure of the music to
1738 be seen at a glance, and any unmatched brackets will be obvious.
1739 Note too how the LH staff is created using double angle brackets
1740 because it requires two voices for its music, whereas the RH staff
1741 is created with a single music expression surrounded by curly
1742 brackets because it requires only one voice.)
1744 @cindex contexts, naming
1745 @cindex naming contexts
1747 The @code{\new} command may also give an identifying name to the
1748 context to distinguish it from other contexts of the same type,
1751 \new @var{type} = @var{id} @var{music-expression}
1754 Note the distinction between the name of the context type,
1755 @code{Staff}, @code{Voice}, etc, and the identifying name of a
1756 particular instance of that type, which can be any sequence of letters
1757 invented by the user. Digits and spaces can also be used in the
1758 identifying name, but then it has to be placed in quotes,
1759 i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
1760 The identifying name is used to
1761 refer back to that particular instance of a context. We saw this in
1762 use in the section on lyrics, see @ref{Voices and vocals}.
1766 Notation Reference: @ruser{Creating contexts}.
1769 @node Engravers explained
1771 @subsection Engravers explained
1775 Every mark on the printed output of a score produced by LilyPond
1776 is produced by an @code{Engraver}. Thus there is an engraver
1777 to print staves, one to print note heads, one for stems, one for
1778 beams, etc, etc. In total there are over 120 such engravers!
1779 Fortunately, for most scores it is not necessary to know about
1780 more than a few, and for simple scores you do not need to know
1783 Engravers live and operate in Contexts. Engravers such as the
1784 @code{Metronome_mark_engraver}, whose action and output apply to the
1785 score as a whole, operate in the highest level context -- the
1786 @code{Score} context.
1788 The @code{Clef_engraver} and @code{Key_engraver} are to be
1789 found in every @code{Staff} Context, as different staves may require
1790 different clefs and keys.
1792 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1793 in every @code{Voice} context, the lowest level context of all.
1795 Each engraver processes the particular objects associated
1796 with its function, and maintains the properties that relate
1797 to that function. These properties, like the properties
1798 associated with contexts, may be modified to change the
1799 operation of the engraver or the appearance of those elements
1800 in the printed score.
1802 Engravers all have compound names formed from words which
1803 describe their function. Just the first word is capitalized,
1804 and the remainder are joined to it with underscores. Thus
1805 the @code{Staff_symbol_engraver} is responsible for creating the
1806 lines of the staff, the @code{Clef_engraver} determines and sets
1807 the pitch reference point on the staff by drawing a clef symbol.
1809 Here are some of the most common engravers together with their
1810 function. You will see it is usually easy to guess the function
1811 from the name, or vice versa.
1813 @multitable @columnfractions .3 .7
1816 @item Accidental_engraver
1817 @tab Makes accidentals, cautionary and suggested accidentals
1822 @item Completion_heads_engraver
1823 @tab Splits notes which cross bar lines
1824 @c The old Dynamic_engraver is deprecated. -jm
1825 @item New_dynamic_engraver
1826 @tab Creates hairpins and dynamic texts
1827 @item Forbid_line_break_engraver
1828 @tab Prevents line breaks if a musical element is still active
1830 @tab Creates the key signature
1831 @item Metronome_mark_engraver
1832 @tab Engraves metronome marking
1833 @item Note_heads_engraver
1834 @tab Engraves note heads
1837 @item Staff_symbol_engraver
1838 @tab Engraves the five (by default) lines of the staff
1840 @tab Creates stems and single-stem tremolos
1841 @item Time_signature_engraver
1842 @tab Creates time signatures
1847 We shall see later how the output of LilyPond can be changed
1848 by modifying the action of Engravers.
1852 Internals reference: @rinternals{Engravers and Performers}.
1855 @node Modifying context properties
1857 @subsection Modifying context properties
1859 @cindex context properties
1860 @cindex context properties, modifying
1861 @cindex modifying context properties
1867 Contexts are responsible for holding the values of a number of
1868 context @emph{properties}. Many of them can be changed to
1869 influence the interpretation of the input and so change the
1870 appearance of the output. They are changed by the
1871 @code{\set} command. This takes the form
1874 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1877 Where the @emph{ContextName} is usually @code{Score},
1878 @code{Staff} or @code{Voice}. It may be omitted,
1879 in which case the current context (typically @code{Voice}) is assumed.
1881 The names of context properties consist of words joined
1882 together with no hyphens or underscores, all except the
1883 first having a capital letter. Here are a few examples
1884 of some commonly used ones. There are many more.
1886 @c attempt to force this onto a new page
1888 @multitable @columnfractions .25 .15 .45 .15
1889 @headitem propertyName
1895 @tab If true, set extra natural signs before accidentals
1896 @tab @code{#t}, @code{#f}
1897 @item currentBarNumber
1899 @tab Set the current bar number
1903 @tab If true, print slurs both above and below notes
1904 @tab @code{#t}, @code{#f}
1905 @item instrumentName
1907 @tab Set the name to be placed at the start of the staff
1908 @tab @code{"Cello I"}
1911 @tab Increase or decrease the font size
1915 @tab Set the text to print before the start of a verse
1920 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1921 an Integer is a positive whole number, a Real is a positive
1922 or negative decimal number, and text is enclosed in double
1923 apostrophes. Note the occurrence of hash signs,
1924 (@code{#}), in two different places -- as part of the Boolean
1925 value before the @code{t} or @code{f}, and before @emph{value}
1926 in the @code{\set} statement. So when a Boolean is being
1927 entered you need to code two hash signs, e.g., @code{##t}.
1929 @cindex properties operating in contexts
1930 @cindex setting properties within contexts
1932 Before we can set any of these properties we need to know
1933 in which context they operate. Sometimes this is obvious,
1934 but occasionally it can be tricky. If the wrong context
1935 is specified, no error message is produced, but the expected
1936 action will not take place. For example, the
1937 @code{instrumentName} clearly lives in the @code{Staff} context, since
1938 it is the staff that is to be named.
1939 In this example the first staff is labelled, but not the second,
1940 because we omitted the context name.
1942 @lilypond[quote,verbatim,ragged-right]
1944 \new Staff \relative c'' {
1945 \set Staff.instrumentName = #"Soprano"
1948 \new Staff \relative c' {
1949 \set instrumentName = #"Alto" % Wrong!
1955 Remember the default context name is @code{Voice}, so the second
1956 @code{\set} command set the property @code{instrumentName} in the
1957 @code{Voice} context to @qq{Alto}, but as LilyPond does not look
1958 for any such property in the @code{Voice} context, no
1959 further action took place. This is not an error, and no error
1960 message is logged in the log file.
1962 Similarly, if the property name is mis-spelt no error message is
1963 produced, and clearly the expected action cannot be performed. In
1964 fact, you can set any (fictitious) @q{property} using any name you
1965 like in any context that exists by using the @code{\set} command. But
1966 if the name is not known to LilyPond it will not cause any action to
1967 be taken. Some text editors with special support for LilyPond input
1968 files document property names with bullets when you hover them with
1969 the mouse, like JEdit with LilyPondTool, or highlight unknown property
1970 names differently, like ConTEXT. If you do not use an editor with
1971 such features, it is recommended to check the property name in the
1972 Internals Reference: see @rinternals{Tunable context properties}, or
1973 @rinternals{Contexts}.
1975 The @code{instrumentName} property will take effect only
1976 if it is set in the @code{Staff} context, but
1977 some properties can be set in more than one context.
1978 For example, the property @code{extraNatural} is by
1979 default set to ##t (true) for all staves.
1980 If it is set to ##f (false) in one particular @code{Staff}
1981 context it applies just to the accidentals on that staff.
1982 If it is set to false in the @code{Score} context
1983 it applies to all staves.
1985 So this turns off extra naturals in one staff:
1987 @lilypond[quote,verbatim,ragged-right]
1989 \new Staff \relative c'' {
1992 \new Staff \relative c'' {
1993 \set Staff.extraNatural = ##f
2000 and this turns them off in all staves:
2002 @lilypond[quote,verbatim,ragged-right]
2004 \new Staff \relative c'' {
2007 \new Staff \relative c'' {
2008 \set Score.extraNatural = ##f
2014 As another example, if @code{clefOctavation} is set in
2015 the @code{Score} context this immediately changes the value
2016 of the octavation in all current staves and sets a new default
2017 value which will be applied to all staves.
2019 The opposite command, @code{\unset}, effectively removes the
2020 property from the context, which causes most properties to
2021 revert to their default value. Usually @code{\unset} is not
2022 required as a new @code{\set} command will achieve what is
2025 The @code{\set} and @code{\unset} commands can appear anywhere
2026 in the input file and will take effect from the time they are
2027 encountered until the end of the score or until the property is
2028 @code{\set} or @code{\unset} again. Let's try changing the
2029 font size, which affects the size of the note heads (among
2030 other things) several times. The change is from the default
2031 value, not the most recently set value.
2033 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
2035 % make note heads smaller
2038 % make note heads larger
2039 \set fontSize = #2.5
2041 % return to default size
2046 We have now seen how to set the values of several different types of
2047 property. Note that integers and numbers are always preceded by a
2048 hash sign, @code{#}, while a true or false value is specified by
2049 @code{##t} and @code{##f}, with two hash signs. A text property
2050 should be enclosed in double quotation signs, as above, although we
2051 shall see later that text can actually be specified in a much more
2052 general way by using the very powerful @code{\markup} command.
2054 @subsubheading Setting context properties with @code{\with}
2058 @cindex context properties, setting with \with
2060 The default value of context properties may be set at the time the
2061 context is created. Sometimes this is a clearer way of setting a
2062 property value if it is to remain fixed for the duration of
2063 the context. When a context is created with a @code{\new}
2064 command it may be followed immediately by a @code{\with @{ .. @}}
2065 block in which the default property values are set. For example,
2066 if we wish to suppress the printing of extra naturals for the
2067 duration of a staff we would write:
2070 \new Staff \with @{ extraNatural = ##f @}
2076 @lilypond[quote,verbatim,ragged-right]
2082 \new Staff \with { extraNatural = ##f }
2089 Or, if the property override is to be applied to all staves
2090 within the score, it may be appended to an explicit
2091 @code{\new Score} command, like this:
2093 @lilypond[quote,verbatim,ragged-right]
2095 \new Score \with { extraNatural = ##f } <<
2110 Properties set in this way may still be changed dynamically using
2111 @code{\set} and returned to the default value set in the
2112 @code{\with} block with @code{\unset}.
2114 @cindex fontSize, default and setting
2116 So if the @code{fontSize} property is set in a @code{\with} clause
2117 it sets the default value of the font size. If it is later changed
2118 with @code{\set}, this new default value may be restored with the
2119 @code{\unset fontSize} command.
2121 @subsubheading Setting context properties with @code{\context}
2123 @cindex context properties, setting with \context
2127 The values of context properties may be set in @emph{all} contexts
2128 of a particular type, such as all @code{Staff} contexts, with a single
2129 command. The context type is identified by using its
2130 type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
2131 The statement which sets the property value is the same as that in a
2132 @code{\with} block, introduced above. It is placed in a
2133 @code{\context} block within a @code{\layout} block. Each
2134 @code{\context} block will affect all contexts of the type specified
2135 throughout the @code{\score} or @code{\book} block in which the
2136 @code{\layout} block appears. Here is a example to show the format:
2138 @lilypond[verbatim,quote]
2155 Context properties set in this way may be overridden for particular
2156 instances of contexts by statements in a @code{\with} block, and by
2157 @code{\set} commands embedded in music statements.
2162 @ruser{Changing context default settings}.
2163 @ruser{The set command}.
2165 Internals Reference:
2166 @rinternals{Contexts},
2167 @rinternals{Tunable context properties}.
2170 @node Adding and removing engravers
2172 @subsection Adding and removing engravers
2174 @cindex engravers, adding
2175 @cindex adding engravers
2176 @cindex engravers, removing
2177 @cindex removing engravers
2184 We have seen that contexts each contain several engravers, each
2185 of which is responsible for producing a particular part of the
2186 output, like bar lines, staves, note heads, stems, etc. If an
2187 engraver is removed from a context, it can no longer produce its
2188 output. This is a crude way of modifying the output, but it
2189 can sometimes be useful.
2191 @subsubheading Changing a single context
2193 To remove an engraver from a single context we use the
2194 @code{\with} command placed immediately after the context creation
2195 command, as in the previous section.
2197 As an illustration, let's repeat an example from the previous section
2198 with the staff lines removed. Remember that the staff lines are
2199 produced by the @code{Staff_symbol_engraver}.
2201 @lilypond[quote,verbatim,ragged-right]
2203 \remove Staff_symbol_engraver
2207 \set fontSize = #-4 % make note heads smaller
2209 \set fontSize = #2.5 % make note heads larger
2211 \unset fontSize % return to default size
2216 @cindex ambitus engraver
2218 Engravers can also be added to individual contexts.
2219 The command to do this is
2221 @code{\consists @var{Engraver_name}},
2224 placed inside a @code{\with} block. Some vocal scores have an ambitus
2225 placed at the beginning of a staff to indicate the range of notes in
2226 that staff -- see @rglos{ambitus}. The ambitus is produced by the
2227 @code{Ambitus_engraver}, which is not normally included in any
2228 context. If we add it to the @code{Voice} context, it calculates the
2229 range from that voice only:
2231 @lilypond[quote,verbatim,ragged-right]
2234 \consists Ambitus_engraver
2249 but if we add the ambitus engraver to the
2250 @code{Staff} context, it calculates the range from all
2251 the notes in all the voices on that staff:
2253 @lilypond[quote,verbatim,ragged-right]
2255 \consists Ambitus_engraver
2271 @subsubheading Changing all contexts of the same type
2276 The examples above show how to remove or add engravers to
2277 individual contexts. It is also possible to remove or add
2278 engravers to every context of a specific type by placing the
2279 commands in the appropriate context in a @code{\layout}
2280 block. For example, if we wanted to show an ambitus for every
2281 staff in a four-staff score, we could write
2283 @lilypond[quote,verbatim,ragged-right]
2312 \consists Ambitus_engraver
2319 The values of context properties may also be set
2320 for all contexts of a particular type by including the
2321 @code{\set} command in a @code{\context} block in the
2326 Notation Reference: @ruser{Modifying context plug-ins},
2327 @ruser{Changing context default settings}.
2330 @node Extending the templates
2332 @section Extending the templates
2334 You've read the tutorial, you know how to write music, you
2335 understand the fundamental concepts. But how can you
2336 get the staves that you want? Well, you can find lots of
2337 templates (see @ref{Templates}) which may give you a start.
2338 But what if you want something that isn't covered there? Read on.
2341 * Soprano and cello::
2342 * Four-part SATB vocal score::
2343 * Building a score from scratch::
2344 * Saving typing with variables and functions::
2345 * Scores and parts::
2348 @node Soprano and cello
2350 @subsection Soprano and cello
2352 @cindex template, modifying
2353 @cindex modifying templates
2355 Start off with the template that seems closest to what you want to
2356 end up with. Let's say that you want to write something for
2357 soprano and cello. In this case, we would start with the
2358 @q{Notes and lyrics} template (for the soprano part).
2361 \version @w{"@version{}"}
2362 melody = \relative c' @{
2369 text = \lyricmode @{
2375 \new Voice = "one" @{
2379 \new Lyrics \lyricsto "one" \text
2386 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2389 \version @w{"@version{}"}
2390 melody = \relative c' @{
2404 We don't need two @code{\version} commands. We'll need the
2405 @code{melody} section. We don't want two @code{\score} sections
2406 -- if we had two @code{\score}s, we'd get the two parts separately.
2407 We want them together, as a duet. Within the @code{\score}
2408 section, we don't need two @code{\layout} or @code{\midi}.
2410 If we simply cut and paste the @code{melody} section, we would
2411 end up with two @code{melody} definitions. This would not generate
2412 an error, but the second one would be used for both melodies.
2413 So let's rename them to make them distinct. We'll call the
2414 section for the soprano @code{sopranoMusic} and the section for
2415 the cello @code{celloMusic}. While we're doing this, let's rename
2416 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2417 instances of all these names -- both the initial definition (the
2418 @code{melody = \relative c' @{ } part) and the name's use (in the
2419 @code{\score} section).
2421 While we're doing this, let's change the cello part's staff --
2422 celli normally use bass clef. We'll also give the cello some
2426 \version @w{"@version{}"}
2427 sopranoMusic = \relative c' @{
2434 sopranoLyrics = \lyricmode @{
2438 celloMusic = \relative c @{
2447 \new Voice = "one" @{
2451 \new Lyrics \lyricsto "one" \sopranoLyrics
2458 This is looking promising, but the cello part won't appear in the
2459 score -- we haven't used it in the @code{\score} section. If we
2460 want the cello part to appear under the soprano part, we need to add
2463 \new Staff \celloMusic
2467 underneath the soprano stuff. We also need to add @code{<<} and
2468 @code{>>} around the music -- that tells LilyPond that there's
2469 more than one thing (in this case, two @code{Staves}) happening
2470 at once. The @code{\score} looks like this now:
2472 @c Indentation in this example is deliberately poor
2477 \new Voice = "one" @{
2481 \new Lyrics \lyricsto "one" \sopranoLyrics
2483 \new Staff \celloMusic
2491 This looks a bit messy; the indentation is messed up now. That is
2492 easily fixed. Here's the complete soprano and cello template.
2494 @lilypond[quote,verbatim,ragged-right,addversion]
2495 sopranoMusic = \relative c' {
2502 sopranoLyrics = \lyricmode {
2506 celloMusic = \relative c {
2516 \new Voice = "one" {
2520 \new Lyrics \lyricsto "one" \sopranoLyrics
2522 \new Staff \celloMusic
2531 The starting templates can be found in the @q{Templates} appendix,
2532 see @ref{Single staff}.
2535 @node Four-part SATB vocal score
2537 @subsection Four-part SATB vocal score
2539 @cindex template, SATB
2540 @cindex SATB template
2542 Most vocal scores of music written for four-part mixed choir
2543 with orchestral accompaniment such as Mendelssohn's Elijah or
2544 Handel's Messiah have the choral music and words on four
2545 staves, one for each of SATB, with a piano reduction of the
2546 orchestral accompaniment underneath. Here's an example
2547 from Handel's Messiah:
2549 @c The following should appear as music without code
2550 @lilypond[quote,ragged-right]
2551 global = { \key d \major \time 4/4 }
2552 sopranoMusic = \relative c'' {
2554 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2556 sopranoWords = \lyricmode {
2557 Wor -- thy is the lamb that was slain
2559 altoMusic = \relative a' {
2561 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
2563 altoWords = \sopranoWords
2564 tenorMusic = \relative c' {
2566 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2568 tenorWords = \sopranoWords
2569 bassMusic = \relative c' {
2571 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2573 bassWords = \sopranoWords
2574 upper = \relative a' {
2577 r4 <a d fis>2 <a e' a>4
2578 <d fis d'>4. <d fis d'>8 <a d a'>2
2579 <g cis g'>4 <a d fis> <a cis e>2
2581 lower = \relative c, {
2584 <d d'>4 <d d'>2 <cis cis'>4
2585 <b b'>4. <b' b'>8 <fis fis'>2
2586 <e e'>4 <d d'> <a' a'>2
2590 << % combine ChoirStaff and PianoStaff in parallel
2592 \new Staff = "sopranos" <<
2593 \set Staff.instrumentName = #"Soprano"
2594 \new Voice = "sopranos" {
2599 \new Lyrics \lyricsto "sopranos" {
2602 \new Staff = "altos" <<
2603 \set Staff.instrumentName = #"Alto"
2604 \new Voice = "altos" {
2609 \new Lyrics \lyricsto "altos" { \altoWords }
2610 \new Staff = "tenors" <<
2611 \set Staff.instrumentName = #"Tenor"
2612 \new Voice = "tenors" {
2617 \new Lyrics \lyricsto "tenors" { \tenorWords }
2618 \new Staff = "basses" <<
2619 \set Staff.instrumentName = #"Bass"
2620 \new Voice = "basses" {
2625 \new Lyrics \lyricsto "basses" {
2630 \set PianoStaff.instrumentName = #"Piano"
2631 \new Staff = "upper" \upper
2632 \new Staff = "lower" \lower
2638 None of the templates provides this layout exactly. The nearest is
2639 @q{SATB vocal score and automatic piano reduction} -- see @ref{Vocal
2640 ensembles} -- but we need to change the layout and add a piano
2641 accompaniment which is not derived automatically from the vocal parts.
2642 The variables holding the music and words for the vocal parts are
2643 fine, but we shall need to add variables for the piano reduction.
2645 The order in which the contexts appear in the ChoirStaff of the
2646 template do not correspond with the order in the vocal score shown
2647 above. We need to rearrange them so there are four staves with the
2648 words written directly underneath the notes for each part. All the
2649 voices should be @code{\voiceOne}, which is the default, so the
2650 @code{\voiceXXX} commands should be removed. We also need to specify
2651 the tenor clef for the tenors. The way in which lyrics are specified
2652 in the template has not yet been encountered so we need to use the
2653 method with which we are familiar. We should also add the names of
2656 Doing this gives for our ChoirStaff:
2660 \new Staff = "sopranos" <<
2661 \set Staff.instrumentName = #"Soprano"
2662 \new Voice = "sopranos" @{
2667 \new Lyrics \lyricsto "sopranos" @{
2670 \new Staff = "altos" <<
2671 \set Staff.instrumentName = #"Alto"
2672 \new Voice = "altos" @{
2677 \new Lyrics \lyricsto "altos" @{
2680 \new Staff = "tenors" <<
2681 \set Staff.instrumentName = #"Tenor"
2682 \new Voice = "tenors" @{
2687 \new Lyrics \lyricsto "tenors" @{
2690 \new Staff = "basses" <<
2691 \set Staff.instrumentName = #"Bass"
2692 \new Voice = "basses" @{
2697 \new Lyrics \lyricsto "basses" @{
2703 Next we must work out the piano part. This is
2704 easy - we just pull out the piano part from the
2705 @q{Solo piano} template:
2709 \set PianoStaff.instrumentName = #"Piano "
2710 \new Staff = "upper" \upper
2711 \new Staff = "lower" \lower
2715 and add the variable definitions for @code{upper}
2718 The ChoirStaff and PianoStaff must be combined
2719 using angle brackets as we want them to be
2720 stacked one above the other:
2723 << % combine ChoirStaff and PianoStaff one above the other
2725 \new Staff = "sopranos" <<
2726 \new Voice = "sopranos" @{
2731 \new Lyrics \lyricsto "sopranos" @{
2734 \new Staff = "altos" <<
2735 \new Voice = "altos" @{
2740 \new Lyrics \lyricsto "altos" @{
2743 \new Staff = "tenors" <<
2744 \clef "G_8" % tenor clef
2745 \new Voice = "tenors" @{
2750 \new Lyrics \lyricsto "tenors" @{
2753 \new Staff = "basses" <<
2755 \new Voice = "basses" @{
2760 \new Lyrics \lyricsto "basses" @{
2766 \set PianoStaff.instrumentName = #"Piano"
2767 \new Staff = "upper" \upper
2768 \new Staff = "lower" \lower
2773 Combining all these together and adding the music
2774 for the three bars of the example above gives:
2776 @lilypond[quote,verbatim,ragged-right,addversion]
2781 sopranoMusic = \relative c'' {
2783 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2785 sopranoWords = \lyricmode {
2786 Wor -- thy is the lamb that was slain
2788 altoMusic = \relative a' {
2790 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2792 altoWords = \sopranoWords
2793 tenorMusic = \relative c' {
2795 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2797 tenorWords = \sopranoWords
2798 bassMusic = \relative c' {
2800 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2802 bassWords = \sopranoWords
2803 upper = \relative a' {
2806 r4 <a d fis>2 <a e' a>4
2807 <d fis d'>4. <d fis d'>8 <a d a'>2
2808 <g cis g'>4 <a d fis> <a cis e>2
2810 lower = \relative c, {
2813 <d d'>4 <d d'>2 <cis cis'>4
2814 <b b'>4. <b' b'>8 <fis fis'>2
2815 <e e'>4 <d d'> <a' a'>2
2819 << % combine ChoirStaff and PianoStaff in parallel
2821 \new Staff = "sopranos" <<
2822 \set Staff.instrumentName = #"Soprano"
2823 \new Voice = "sopranos" {
2828 \new Lyrics \lyricsto "sopranos" {
2831 \new Staff = "altos" <<
2832 \set Staff.instrumentName = #"Alto"
2833 \new Voice = "altos" {
2838 \new Lyrics \lyricsto "altos" {
2841 \new Staff = "tenors" <<
2842 \set Staff.instrumentName = #"Tenor"
2843 \new Voice = "tenors" {
2848 \new Lyrics \lyricsto "tenors" {
2851 \new Staff = "basses" <<
2852 \set Staff.instrumentName = #"Bass"
2853 \new Voice = "basses" {
2858 \new Lyrics \lyricsto "basses" {
2864 \set PianoStaff.instrumentName = #"Piano "
2865 \new Staff = "upper" \upper
2866 \new Staff = "lower" \lower
2873 @node Building a score from scratch
2875 @subsection Building a score from scratch
2877 @cindex template, writing your own
2878 @cindex example of writing a score
2879 @cindex writing a score, example
2880 @cindex score, example of writing
2882 After gaining some facility with writing LilyPond code, you
2883 may find that it is easier to build a score from scratch
2884 rather than modifying one of the templates. You can also
2885 develop your own style this way to suit the sort of music you
2886 like. Let's see how to put together the score for an organ
2887 prelude as an example.
2889 We begin with a header section. Here go the title, name
2890 of composer, etc, then come any variable definitions, and
2891 finally the score block. Let's start with these in outline
2892 and fill in the details later.
2894 We'll use the first two bars of Bach's prelude
2895 based on @emph{Jesu, meine Freude} which is written for two
2896 manuals and pedal organ. You can see these two bars of music
2897 at the bottom of this section. The top manual part has two voices,
2898 the lower and pedal organ one each. So we need four
2899 music definitions and one to define the time signature
2903 \version @w{"@version{}"}
2905 title = "Jesu, meine Freude"
2906 composer = "J S Bach"
2912 ManualOneVoiceOneMusic = @{ s1 @}
2913 ManualOneVoiceTwoMusic = @{ s1 @}
2914 ManualTwoMusic = @{ s1 @}
2915 PedalOrganMusic = @{ s1 @}
2921 For now we've just used a spacer note, @code{s1},
2922 instead of the real music. We'll add that later.
2924 Next let's see what should go in the score block.
2925 We simply mirror the staff structure we want.
2926 Organ music is usually written on three staves,
2927 one for each manual and one for the pedals. The
2928 manual staves should be bracketed together, so we
2929 need to use a PianoStaff for them. The first
2930 manual part needs two voices and the second manual
2935 \new Staff = "ManualOne" <<
2937 \ManualOneVoiceOneMusic
2940 \ManualOneVoiceTwoMusic
2942 >> % end ManualOne Staff context
2943 \new Staff = "ManualTwo" <<
2947 >> % end ManualTwo Staff context
2948 >> % end PianoStaff context
2951 Next we need to add a staff for the pedal organ.
2952 This goes underneath the PianoStaff, but it must
2953 be simultaneous with it, so we need angle brackets
2954 around the two. Missing these out would generate
2955 an error in the log file. It's a common mistake
2956 which you'll make sooner or later! Try copying
2957 the final example at the end of this section,
2958 remove these angle brackets, and compile it to
2959 see what errors it generates.
2962 << % PianoStaff and Pedal Staff must be simultaneous
2964 \new Staff = "ManualOne" <<
2966 \ManualOneVoiceOneMusic
2969 \ManualOneVoiceTwoMusic
2971 >> % end ManualOne Staff context
2972 \new Staff = "ManualTwo" <<
2976 >> % end ManualTwo Staff context
2977 >> % end PianoStaff context
2978 \new Staff = "PedalOrgan" <<
2986 It is not necessary to use the simultaneous construct
2987 @code{<< .. >>} for the manual two staff and the pedal organ staff,
2988 since they contain only one music expression, but it does no harm,
2989 and always using angle brackets after @code{\new Staff} is a good
2990 habit to cultivate in case there are multiple voices. The opposite
2991 is true for Voices: these should habitually be followed by braces
2992 @code{@{ .. @}} in case your music is coded in several variables
2993 which need to run consecutively.
2995 Let's add this structure to the score block, and adjust the indenting.
2996 We also add the appropriate clefs, ensure stems, ties and slurs in
2997 each voice on the upper staff point to the right direction with
2998 @code{\voiceOne} and @code{\voiceTwo}, and enter the time signature
2999 and key to each staff using our predefined variable, @code{\TimeKey}.
3003 << % PianoStaff and Pedal Staff must be simultaneous
3005 \new Staff = "ManualOne" <<
3006 \TimeKey % set time signature and key
3010 \ManualOneVoiceOneMusic
3014 \ManualOneVoiceTwoMusic
3016 >> % end ManualOne Staff context
3017 \new Staff = "ManualTwo" <<
3023 >> % end ManualTwo Staff context
3024 >> % end PianoStaff context
3025 \new Staff = "PedalOrgan" <<
3031 >> % end PedalOrgan Staff
3033 @} % end Score context
3036 That completes the structure. Any three-staff organ music
3037 will have a similar structure, although the number of voices
3038 may vary. All that remains now
3039 is to add the music, and combine all the parts together.
3041 @lilypond[quote,verbatim,ragged-right,addversion]
3043 title = "Jesu, meine Freude"
3044 composer = "J S Bach"
3050 ManualOneVoiceOneMusic = \relative g' {
3054 ManualOneVoiceTwoMusic = \relative c' {
3055 ees16 d ees8~ ees16 f ees d c8 d~ d c~
3056 c c4 b8 c8. g16 c b c d
3058 ManualTwoMusic = \relative c' {
3059 c16 b c8~ c16 b c g a8 g~ g16 g aes ees
3060 f ees f d g aes g f ees d e8~ ees16 f ees d
3062 PedalOrganMusic = \relative c {
3063 r8 c16 d ees d ees8~ ees16 a, b g c b c8
3064 r16 g ees f g f g8 c,2
3068 << % PianoStaff and Pedal Staff must be simultaneous
3070 \new Staff = "ManualOne" <<
3071 \TimeKey % set time signature and key
3075 \ManualOneVoiceOneMusic
3079 \ManualOneVoiceTwoMusic
3081 >> % end ManualOne Staff context
3082 \new Staff = "ManualTwo" <<
3088 >> % end ManualTwo Staff context
3089 >> % end PianoStaff context
3090 \new Staff = "PedalOrgan" <<
3096 >> % end PedalOrgan Staff context
3098 } % end Score context
3102 @node Saving typing with variables and functions
3104 @subsection Saving typing with variables and functions
3109 By this point, you've seen this kind of thing:
3111 @lilypond[quote,verbatim,ragged-right]
3112 hornNotes = \relative c'' { c4 b dis c }
3120 You may even realize that this could be useful in minimalist music:
3122 @lilypond[quote,verbatim,ragged-right]
3123 fragmentA = \relative c'' { a4 a8. b16 }
3124 fragmentB = \relative c'' { a8. gis16 ees4 }
3125 violin = \new Staff {
3138 However, you can also use these variables (also known as
3139 macros, or user-defined commands) for tweaks:
3141 @c TODO Avoid padtext - not needed with skylining
3142 @lilypond[quote,verbatim,ragged-right]
3143 dolce = \markup { \italic \bold dolce }
3144 padText = { \once \override TextScript #'padding = #5.0 }
3145 fthenp=_\markup { \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
3146 violin = \relative c'' {
3148 c4._\dolce b8 a8 g a b
3150 c4.^"hi there!" d8 e' f g d
3151 c,4.\fthenp b8 c4 c-.
3158 \layout { ragged-right=##t }
3162 These variables are obviously useful for saving
3163 typing. But they're worth considering even if you
3164 only use them once -- they reduce complexity. Let's
3165 look at the previous example without any
3166 variables. It's a lot harder to read, especially
3170 violin = \relative c'' @{
3172 c4._\markup @{ \italic \bold dolce @} b8 a8 g a b
3173 \once \override TextScript #'padding = #5.0
3174 c4.^"hi there!" d8 e' f g d
3175 c,4.\markup @{ \dynamic f \italic \small @{ 2nd @}
3176 \hspace #0.1 \dynamic p @}
3182 @c TODO Replace the following with a better example -td
3183 @c Skylining handles this correctly without padText
3185 So far we've seen static substitution -- when LilyPond
3186 sees @code{\padText}, it replaces it with the stuff that
3187 we've defined it to be (ie the stuff to the right of
3190 LilyPond can handle non-static substitution, too (you
3191 can think of these as functions).
3193 @lilypond[quote,verbatim,ragged-right]
3195 #(define-music-function (parser location padding) (number?)
3197 \once \override TextScript #'padding = #$padding
3201 c4^"piu mosso" b a b
3203 c4^"piu mosso" d e f
3205 c4^"piu mosso" fis a g
3209 Using variables is also a good way to reduce work if the
3210 LilyPond input syntax changes (see
3211 @rprogram{Updating files with convert-ly}). If
3212 you have a single definition (such as @code{\dolce}) for all your
3213 input files (see @ref{Style sheets}), then if the syntax changes, you
3214 only need to update your single @code{\dolce} definition,
3215 instead of making changes throughout every @code{.ly} file.
3218 @node Scores and parts
3220 @subsection Scores and parts
3222 In orchestral music, all notes are printed twice. Once in a part for
3223 the musicians, and once in a full score for the conductor. Variables can
3224 be used to avoid double work. The music is entered once, and stored in
3225 a variable. The contents of that variable is then used to generate
3226 both the part and the full score.
3228 It is convenient to define the notes in a special file. For example,
3229 suppose that the file @file{horn-music.ly} contains the following part
3230 of a horn/@/bassoon duo
3233 hornNotes = \relative c @{
3240 Then, an individual part is made by putting the following in a file
3243 \include "horn-music.ly"
3245 instrument = "Horn in F"
3249 \transpose f c' \hornNotes
3256 \include "horn-music.ly"
3260 substitutes the contents of @file{horn-music.ly} at this position in
3261 the file, so @code{hornNotes} is defined afterwards. The command
3262 @code{\transpose f@tie{}c'} indicates that the argument, being
3263 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
3264 @code{f} is denoted by notated @code{c'}, which corresponds with the
3265 tuning of a normal French Horn in@tie{}F. The transposition can be seen
3266 in the following output
3268 @lilypond[quote,ragged-right]
3269 \transpose f c' \relative c {
3275 In ensemble pieces, one of the voices often does not play for many
3276 measures. This is denoted by a special rest, the multi-measure
3277 rest. It is entered with a capital @code{R} followed by a duration
3278 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
3279 etc.). By multiplying the
3280 duration, longer rests can be constructed. For example, this rest
3281 takes 3@tie{}measures in 2/4 time
3287 When printing the part, multi-rests
3288 must be condensed. This is done by setting a run-time variable
3291 \set Score.skipBars = ##t
3295 This command sets the property @code{skipBars} in the
3296 @code{Score} context to true (@code{##t}). Prepending the rest and
3297 this option to the music above, leads to the following result
3299 @lilypond[quote,ragged-right]
3300 \transpose f c' \relative c {
3302 \set Score.skipBars = ##t
3309 The score is made by combining all of the music together. Assuming
3310 that the other voice is in @code{bassoonNotes} in the file
3311 @file{bassoon-music.ly}, a score is made with
3314 \include "bassoon-music.ly"
3315 \include "horn-music.ly"
3318 \new Staff \hornNotes
3319 \new Staff \bassoonNotes
3326 @lilypond[quote,ragged-right]
3335 r4 d,8 f | gis4 c | b bes |
3336 a8 e f4 | g d | gis f |