1 @c -*- coding: utf-8; mode: texinfo; fill-column: 60 -*-
4 Translation of GIT committish: 12c6693055728e69dce5c4e5a4a2b5f71180a5e2
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{}"}
70 @var{...samengestelde muziekuitdrukking...} % alle muziek komt hier!
77 Er zijn veel variaties op dit basispatroon maar dit
78 voorbeeld dient als een handig beginpunt.
87 Tot nu toe heeft geen van de voorbeelden het
88 @code{\score@{@}}-commando gebruikt. Dit kan omdat LilyPond
89 automatisch de extra commando's toevoegt die benodigt zijn
90 als je het eenvoudige invoer geeft. LilyPond behandelt invoer
100 als een afkorting voor dit:
117 Anders gezegd, als de invoer een enkelvoudige
118 muziekuitdrukking bevat, interpreteert LilyPond het bestand
119 alsof die muziekuitdrukking ingepakt is in bovenstaande
122 @cindex impliciete contexten
123 @cindex contexten, impliciet
125 @strong{Een kleine waarschuwing!} In veel van de voorbeelden
126 in de LilyPond-documentatie worden de @code{\new Staff}- en
127 @code{\new Voice}-commando's weggelaten en worden ze
128 impliciet aangemaakt. Voor eenvoudige voorbeelden werkt dat
129 goed, maar voor ingewikkelde voorbeelden, vooral wanneer
130 additionele commando's worden gebruikt, kan het impliciete
131 aanmaken van contexten verrassende resultaten opleveren,
132 zoals extra ongewenste notebalken. Hoe je contexten
133 expliciet specificeert, wordt uitgelegd in @ref{Contexts and
136 @warning{Voor het invoeren van meer dan enkele regels muziek
137 wordt aangeraden altijd notenbalken en stemmen expliciet te
140 Laten we terugkeren naar het eerste voorbeeld en het
141 @code{\score}-commando beter bekijken.
143 Een @code{\score}-blok moet altijd precies één
144 muziekuitdrukking bevatten, en die moet direct na het
145 @code{\score}-commando staan. Herrinner je dat een
146 muziekuitdrukking alles kan zijn van een enkele noot
147 tot een enorme samengestelde uitdrukking zoals
152 @var{...vul de volledige partituur van een Wagner opera hier in...}
158 Omdat alles tussen @code{@{ ... @}} staat, telt het als één
161 Zoals we eerder al zagen, kan het @code{\score}-blok
162 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 @file{.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 @{
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 iets anders zijn. Bedenk dat je
262 vrijwel elke naam kunt gebruiken die je wilt, zolang die
263 maar bestaat uit letters en het niet de naam is van een
264 LilyPond-commando. Voor meer details, zie @ref{Saving
265 typing with variables and functions}. De precieze
266 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
276 @subsection Score is a (single) compound musical expression
280 @cindex contents of a score block
281 @cindex score block, contents of
282 @cindex compound music expression
283 @cindex music expression, compound
285 We saw the general organization of LilyPond input files in the
286 previous section, @ref{Introduction to the LilyPond file structure}.
287 But we seemed to skip over the most important part: how do we figure
288 out what to write after @code{\score}?
290 We didn't skip over it at all. The big mystery is simply that
291 there @emph{is} no mystery. This line explains it all:
294 @emph{A @code{\score} block must begin with a compound music expression.}
298 To understand what is meant by a music expression and a compound
299 music expression, you may find it useful to review the tutorial,
300 @ref{Music expressions explained}. In that section, we saw how to
301 build big music expressions from small pieces -- we started from
302 notes, then chords, etc. Now we're going to start from a big
303 music expression and work our way down. For simplicity, we'll use
304 just a singer and piano in our example. We don't need a
305 @code{StaffGroup} for this ensemble, which simply groups a number
306 of staves together with a bracket at the left, but we do need
307 staves for a singer and a piano, though.
312 \new Staff = "singer" <<
314 \new PianoStaff = "piano" <<
321 Here we have given names to the staves -- @qq{singer} and
322 @qq{piano}. This is not essential here, but it is a useful habit
323 to cultivate so that you can see at a glance what each stave is
326 Remember that we use @code{<< ... >>} instead of @code{@{ ... @}} to
327 show simultaneous music. This causes the vocal part and piano part
328 to appear one above the other in the score. The @code{<< ... >>}
329 construct would not be necessary for the Singer staff in the example
330 above if it were going to contain only one sequential music
331 expression, but @code{<< ... >>} rather than braces is necessary if
332 the music in the Staff is to contain two or more simultaneous
333 expressions, e.g. two simultaneous Voices, or a Voice with lyrics.
334 We're going to have a voice with lyrics, so angle brackets are
335 required. We'll add some real music later; for now let's just put
336 in some dummy notes and lyrics. If you've forgotten how to add lyrics
337 you may wish to review @code{\addlyrics} in @ref{Setting simple songs}.
339 @lilypond[verbatim,quote,ragged-right]
342 \new Staff = "singer" <<
343 \new Voice = "vocal" { c'1 }
346 \new PianoStaff = "piano" <<
347 \new Staff = "upper" { c'1 }
348 \new Staff = "lower" { c'1 }
355 Now we have a lot more details. We have the singer's staff: it
356 contains a @code{Voice} (in LilyPond, this term refers to a set of
357 notes, not necessarily vocal notes -- for example, a violin
358 generally plays one voice) and some lyrics. We also have a piano
359 staff: it contains an upper staff (right hand) and a lower staff
360 (left hand), although the lower staff has yet to be given a bass
363 At this stage, we could start filling in notes. Inside the curly
364 braces next to @code{\new Voice = "vocal"}, we could start writing
368 r4 d''8\noBeam g, c4 r
372 But if we did that, the @code{\score} section would get pretty
373 long, and it would be harder to understand what was happening. So
374 let's use variables instead. These were introduced at the end
375 of the previous section, remember? To ensure the contents of the
376 @code{text} variable are interpreted as lyrics we preface them with
377 @code{\lyricmode}. Like @code{\addlyrics}, this switches the input
378 mode to lyrics. Without that, LilyPond would try to interpret the
379 contents as notes, which would generate errors. (Several other
380 input modes are available, see @ruser{Input modes}.)
382 So, adding a few notes and a bass clef for the left hand, we now
383 have a piece of real music:
385 @lilypond[verbatim,quote,ragged-right]
386 melody = \relative { r4 d''8\noBeam g, c4 r }
387 text = \lyricmode { And God said, }
388 upper = \relative { <g' d g,>2~ <g d g,> }
389 lower = \relative { b,2 e }
393 \new Staff = "singer" <<
394 \new Voice = "vocal" { \melody }
397 \new PianoStaff = "piano" <<
398 \new Staff = "upper" { \upper }
399 \new Staff = "lower" {
409 When writing (or reading) a @code{\score} section, just take it
410 slowly and carefully. Start with the outer level, then work on
411 each smaller level. It also really helps to be strict with
412 indentation -- make sure that each item on the same level starts
413 on the same horizontal position in your text editor.
417 Notation Reference: @ruser{Structure of a score}.
420 @node Nesting music expressions
421 @subsection Nesting music expressions
423 @cindex staves, temporary
424 @cindex temporary staves
427 It is not essential to declare all staves at the beginning; they may
428 be introduced temporarily at any point. This is particularly useful
429 for creating ossia sections -- see @rglos{ossia}. Here is a simple
430 example showing how to introduce a new staff temporarily for the
431 duration of three notes:
433 @lilypond[verbatim,quote,ragged-right]
450 Note that the size of the clef is the same as a clef printed
451 following a clef change -- slightly smaller than the clef
452 at the beginning of the line. This is usual for clefs printed
453 in the middle of a line.
455 @cindex staff, positioning
457 The ossia section may be placed above the staff
460 @lilypond[verbatim,quote,ragged-right]
461 \new Staff = "main" {
468 alignAboveContext = #"main"
476 This example uses @code{\with}, which will be explained more
477 fully later. It is a means of modifying the default behavior
478 of a single Staff. Here it says that the new staff should be
479 placed above the staff called @qq{main} instead of the default
480 position which is below.
484 Ossia are often written without clef and without
485 time signature and are usually in a smaller font.
486 These require further commands which
487 have not yet been introduced. See @ref{Size of objects},
488 and @ruser{Ossia staves}.
491 @node On the un-nestedness of brackets and ties
492 @subsection On the un-nestedness of brackets and ties
494 @cindex brackets, nesting
495 @cindex bracket types
496 @cindex brackets, enclosing vs. marking
498 You have already met a number of different types of bracket and
499 bracket-like constructs in writing the input file to LilyPond.
500 These obey different rules which can be confusing at first.
501 Let's first review the different types of brackets and bracket-like
504 @c attempt to force this onto a new page
506 @multitable @columnfractions .3 .7
507 @headitem Bracket Type
509 @item @code{@{ .. @}}
510 @tab Encloses a sequential segment of music
512 @tab Encloses the notes of a chord
513 @item @code{<< .. >>}
514 @tab Encloses simultaneous music expressions
516 @tab Marks the start and end of a slur
517 @item @code{\( .. \)}
518 @tab Marks the start and end of a phrasing slur
520 @tab Marks the start and end of a manual beam
523 To these we should add other constructs which generate lines
524 between or across notes: ties (marked by a tilde, @code{~}),
525 tuplets written as @code{\times x/y @{..@}}, and grace notes
526 written as @code{\grace@{..@}}.
528 Outside LilyPond, the conventional use of brackets requires the
529 different types to be properly nested, like this, @code{<< [ @{ ( .. )
530 @} ] >>}, with the closing brackets being encountered in exactly the
531 opposite order to the opening brackets. This @strong{is} a
532 requirement for the three types of bracket described by the word
533 @q{Encloses} in the table above -- they must nest properly. However,
534 the remaining bracket-like constructs, described with the word
535 @q{Marks} in the table above together with ties and tuplets, do
536 @strong{not} have to nest properly with any of the brackets or
537 bracket-like constructs. In fact, these are not brackets in
538 the sense that they enclose something -- they are simply markers to
539 indicate where something starts and ends.
541 So, for example, a phrasing slur can start before a manually
542 inserted beam and end before the end of the beam -- not very
543 musical, perhaps, but possible:
545 @lilypond[quote,verbatim,ragged-right]
546 \relative { g'8\( a b[ c b\) a] g4 }
549 In general, different kinds of brackets, bracket-like constructs,
550 and those implied by tuplets, ties and grace notes, may be mixed
551 freely. This example shows a beam extending into a tuplet (line 1),
552 a slur extending into a tuplet (line 2), a beam and a slur
553 extending into a tuplet, a tie crossing two tuplets, and a
554 phrasing slur extending out of a tuplet (lines 3 and 4).
556 @lilypond[quote,verbatim,ragged-right]
558 r16[ g' \tuplet 3/2 { r16 e'8] }
559 g,16( a \tuplet 3/2 { b16 d) e }
560 g,8[( a \tuplet 3/2 { b8 d) e~] } |
561 \tuplet 5/4 { e32\( a, b d e } a4.\)
566 @node Voices contain music
567 @section Voices contain music
569 Singers need voices to sing, and so does LilyPond.
570 The actual music for all instruments in a score
571 is contained in Voices -- the most fundamental
572 of all LilyPond's concepts.
575 * I'm hearing Voices::
576 * Explicitly instantiating voices::
577 * Voices and vocals::
580 @node I'm hearing Voices
581 @subsection I'm hearing Voices
585 @cindex multiple voices
586 @cindex voices, multiple
587 @cindex Voice context
588 @cindex context, Voice
589 @cindex simultaneous music
590 @cindex music, simultaneous
591 @cindex concurrent music
592 @cindex music, concurrent
593 @cindex voices vs. chords
594 @cindex chords vs. voices
596 The lowest, most fundamental or innermost layers in a LilyPond
597 score are called @q{Voice contexts} or just @q{Voices} for short.
598 Voices are sometimes called @q{layers} in other notation
601 In fact, a Voice layer or context is the only one which can contain
602 music. If a Voice context is not explicitly declared one is created
603 automatically, as we saw at the beginning of this chapter. Some
604 instruments such as an Oboe can play only one note at a time. Music
605 written for such instruments requires just a single voice. Instruments
606 which can play more than one note at a time like the piano will often
607 require multiple voices to encode the different concurrent notes and
608 rhythms they are capable of playing.
610 A single voice can contain many notes in a chord, of course,
611 so when exactly are multiple voices needed? Look first at
612 this example of four chords:
614 @lilypond[quote,verbatim,ragged-right]
617 <d' g>4 <d fis> <d a'> <d g>
621 This can be expressed using just the single angle bracket chord
622 symbols, @code{< ... >}, and for this just a single voice is
623 needed. But suppose the F-sharp were actually an eighth-note
624 followed by an eighth-note G, a passing note on the way to the A?
625 Now we have two notes which start at the same time but have
626 different durations: the quarter-note D and the eighth-note
627 F-sharp. How are these to be coded? They cannot be written as
628 a chord because all the notes in a chord must have the same
629 duration. And they cannot be written as two sequential notes
630 as they need to start at the same time. This is when two
633 Let us see how this is done in LilyPond input syntax.
638 The easiest way to enter fragments with more than one voice on a
639 staff is to enter each voice as a sequence (with @code{@{...@}}),
640 and combine them simultaneously with angle brackets, @code{<<...>>}.
641 The fragments must also be separated with double backward slashes,
642 @code{\\}, to place them in separate voices. Without these, the
643 notes would be entered into a single voice, which would usually
644 cause errors. This technique is particularly suited to pieces of
645 music which are largely homophonic with occasional short sections
648 Here's how we split the chords above into two voices and add both
649 the passing note and a slur:
651 @lilypond[quote,verbatim,ragged-right]
654 % Voice = "1" Voice = "2"
655 << { g'4 fis8( g) a4 g } \\ { d4 d d d } >>
659 Notice how the stems of the second voice now point down.
661 Here's another simple example:
663 @lilypond[quote,verbatim,ragged-right]
666 % Voice = "1" Voice = "2"
667 << { r4 g' g4. a8 } \\ { d,2 d4 g } >> |
668 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
669 << { 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,ragged-right]
682 \relative { % Voice = "1"
687 \relative { % Voice = "2"
696 @cindex voices, naming
697 @cindex voices crossing brackets
698 @cindex slurs crossing brackets
699 @cindex ties crossing brackets
701 This example has just two voices, but the same construct may be
702 used to encode three or more voices by adding more back-slash
705 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
706 The first contexts set the @emph{outer} voices, the highest
707 voice in context @code{"1"} and the lowest voice in context
708 @code{"2"}. The inner voices go in contexts @code{"3"} and
709 @code{"4"}. In each of these contexts, the vertical direction
710 of slurs, stems, ties, dynamics etc., is set appropriately.
712 @lilypond[quote,verbatim]
713 \new Staff \relative {
716 % Voice = "1" Voice = "2" Voice = "3"
717 << { g4 f e } \\ { r8 e4 d c8~ } >> |
718 << { d2 e } \\ { c8 b16 a b8 g~ 2 } \\ { s4 b c2 } >> |
722 These voices are all separate from the main voice that contains
723 the notes just outside the @code{<< .. >>} construct. Let's call
724 this the @emph{simultaneous construct}. Slurs and ties may only
725 connect notes within the same voice, so slurs and ties cannot go
726 into or out of a simultaneous construct. Conversely,
727 parallel voices from separate simultaneous constructs on the same
728 staff are the same voice. Other voice-related properties also
729 carry across simultaneous constructs. Here is the same example,
730 with different colors and note heads for each voice. Note that
731 changes in one voice do not affect other voices, but they do
732 persist in the same voice later. Note also that tied notes may be
733 split across the same voices in two constructs, shown here in the
736 @lilypond[quote,verbatim]
737 \new Staff \relative {
766 @funindex \voiceOneStyle
767 @funindex \voiceTwoStyle
768 @funindex \voiceThreeStyle
769 @funindex \voiceFourStyle
770 @funindex \voiceNeutralStyle
772 The commands @code{\voiceXXXStyle} are mainly intended for use in
773 educational documents such as this one. They modify the color
774 of the note head, the stem and the beams, and the style of the
775 note head, so that the voices may be easily distinguished.
776 Voice one is set to red diamonds, voice two to blue triangles,
777 voice three to green crossed circles, and voice four (not used
778 here) to magenta crosses; @code{\voiceNeutralStyle} (also not
779 used here) reverts the style back to the default.
780 We shall see later how commands like these may be created by the
782 See @ref{Visibility and color of objects} and
783 @ref{Using variables for tweaks}.
785 @cindex polyphony and relative note entry
786 @cindex relative note entry and polyphony
788 Polyphony does not change the relationship of notes within a
789 @code{\relative} block. Each note is still calculated relative to
790 the note immediately preceding it, or to the first note of the
791 preceding chord. So in
794 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
798 @code{noteB} is relative to @code{noteA} @*
799 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
800 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
802 @code{noteE} is relative to @code{noteD}, not @code{noteA}.
804 An alternative way, which may be clearer if the notes in the
805 voices are widely separated, is to place a @code{\relative}
806 command at the start of each voice:
809 \relative c' @{ noteA ... @}
811 \relative c'' @{ < noteB noteC > ... @}
813 \relative g' @{ noteD ... @}
815 \relative c' @{ noteE ... @}
818 Let us finally analyze the voices in a more complex piece of music.
819 Here are the notes from the first two bars of the second of Chopin's
820 Deux Nocturnes, Op 32. This example will be used at later stages in
821 this and the next chapter to illustrate several techniques for
822 producing notation, so please ignore for now anything in the
823 underlying code which looks mysterious and concentrate just on the
824 music and the voices -- the complications will all be explained in
827 @c The following should appear as music without code
828 @lilypond[quote,ragged-right]
829 \new Staff \relative {
835 % Ignore these for now - they are explained in Ch 4
836 \once \override NoteColumn.ignore-collision = ##t
838 \once \override NoteColumn.force-hshift = #0.5
844 \override NoteColumn.force-hshift = #0
852 The direction of the stems is often used to indicate the continuity of
853 two simultaneous melodic lines. Here the stems of the highest notes
854 are all pointing up and the stems of the lower notes are all pointing
855 down. This is the first indication that more than one voice is
858 But the real need for multiple voices arises when notes
859 which start at the same time have different durations.
860 Look at the notes which start at beat three in the first
861 bar. The A-flat is a dotted quarter note, the F is a
862 quarter note and the D-flat is a half note. These
863 cannot be written as a chord as all the notes in a chord
864 must have the same duration. Neither can they be written
865 as sequential notes, as they must start at the same time.
866 This section of the bar requires three voices, and the
867 normal practice would be to write the whole bar as three
868 voices, as shown below, where we have used different note heads
869 and colors for the three voices. Again, the code behind this
870 example will be explained later, so ignore anything you do
873 @c The following should appear as music without code
874 @c The three voice styles should be defined in -init
875 @lilypond[quote,ragged-right]
876 \new Staff \relative {
885 % Ignore these for now - they are explained in Ch 4
886 \once \override NoteColumn.ignore-collision = ##t
888 \once \override NoteColumn.force-hshift = #0.5
891 \\ % No Voice three (we want stems down)
894 \override NoteColumn.force-hshift = #0
903 Let us try to encode this music from scratch. As we
904 shall see, this encounters some difficulties. We begin as
905 we have learnt, using the @code{<< \\ >>} construct to
906 enter the music of the first bar in three voices:
908 @lilypond[quote,verbatim,ragged-right]
909 \new Staff \relative {
912 { c''2 aes4. bes8 } \\ { <ees, c>2 des } \\ { aes'2 f4 fes }
919 @cindex voices and stem directions
920 @cindex stem directions and voices
923 The stem directions are automatically assigned with the
924 odd-numbered voices taking upward stems and the even-numbered
925 voices downward ones. The stems for voices 1 and 2 are right,
926 but the stems in voice 3 should go down in this particular piece
927 of music. We can correct this by skipping voice three
928 and placing the music in voice four. This is done by simply
929 adding another pair of @code{\\}.
931 @lilypond[quote,verbatim,ragged-right]
932 \new Staff \relative {
938 \\ % Omit Voice three
947 We see that this fixes the stem direction, but the horizontal
948 placement of notes is not what we want. LilyPond shifts the
949 inner notes when they or their stems would collide with outer
950 voices, but this is not appropriate for piano music. In other
951 situations, the shifts LilyPond applies might fail to clear
952 the collisions. LilyPond provides several ways to adjust the
953 horizontal placing of notes. We are not quite ready yet to see
954 how to correct this, so we shall leave this problem until a
955 later section --- see the @code{force-hshift} property in
956 @ref{Fixing overlapping notation}.
958 @warning{Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be
959 created @q{across} voices.}
963 Notation Reference: @ruser{Multiple voices}.
966 @node Explicitly instantiating voices
967 @subsection Explicitly instantiating voices
971 @funindex \voiceThree
975 @cindex voice contexts, creating
977 Voice contexts can also be created manually
978 inside a @code{<< >>} block to create polyphonic music, using
979 @code{\voiceOne} @dots{} @code{\voiceFour} to indicate the required
980 directions of stems, slurs, etc. In longer scores this method
981 is clearer, as it permits the voices to be separated and to be
982 given more descriptive names.
984 Specifically, the construct @code{<< \\ >>} which we used in
985 the previous section:
990 << @{ e'4 f g a @} \\ @{ c,4 d e f @} >>
1000 \new Voice = "1" @{ \voiceOne \relative @{ e'4 f g a @} @}
1001 \new Voice = "2" @{ \voiceTwo \relative @{ c'4 d e f @} @}
1005 Both of the above would produce
1007 @c The following example should not display the code
1008 @lilypond[ragged-right,quote]
1010 \new Voice = "1" { \voiceOne \relative { e'4 f g a } }
1011 \new Voice = "2" { \voiceTwo \relative { c'4 d e f } }
1015 @cindex voices, reverting to single
1016 @cindex reverting to a single voice
1018 The @code{\voiceXXX} commands set the direction of stems, slurs,
1019 ties, articulations, text annotations, augmentation dots of dotted
1020 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
1021 make these objects point upwards, while @code{\voiceTwo} and
1022 @code{\voiceFour} make them point downwards. These commands also
1023 generate a horizontal shift for each voice when this is required
1024 to avoid clashes of note heads. The command @code{\oneVoice}
1025 reverts the settings back to the normal values for a single voice.
1027 Let us see in some simple examples exactly what effect
1028 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
1029 markup, ties, slurs, and dynamics:
1031 @lilypond[quote,ragged-right,verbatim]
1033 % Default behavior or behavior after \oneVoice
1034 c'4 d8~ 8 e4( f | g4 a) b-> c |
1038 @lilypond[quote,ragged-right,verbatim]
1041 c'4 d8~ 8 e4( f | g4 a) b-> c |
1043 c,4 d8~ 8 e4( f | g4 a) b-> c |
1047 @lilypond[quote,ragged-right,verbatim]
1050 c'4 d8~ 8 e4( f | g4 a) b-> c |
1052 c,4 d8~ 8 e4( f | g4 a) b-> c |
1056 Now let's look at three different ways to notate the same passage of
1057 polyphonic music, each of which is advantageous in different
1058 circumstances, using the example from the previous section.
1060 An expression that appears directly inside a @code{<< >>} belongs to the
1061 main voice (but, note, @strong{not} in a @code{<< \\ >>} construct).
1062 This is useful when extra voices appear while the main voice is playing.
1063 Here is a more correct rendition of our example. The red diamond-shaped
1064 notes demonstrate that the main melody is now in a single voice context,
1065 permitting a phrasing slur to be drawn over them.
1067 @lilypond[quote,ragged-right,verbatim]
1068 \new Staff \relative {
1070 % This section is homophonic
1072 % Start simultaneous section of three voices
1074 % Continue the main voice in parallel
1075 { g4 f e | d2 e) | }
1076 % Initiate second voice
1078 % Set stems, etc., down
1080 r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
1082 % Initiate third voice
1084 % Set stems, etc, up
1092 @cindex nesting music expressions
1093 @cindex nesting simultaneous constructs
1094 @cindex nesting voices
1095 @cindex voices, temporary
1096 @cindex voices, nesting
1098 More deeply nested polyphony constructs are possible, and if a
1099 voice appears only briefly this might be a more natural way to
1102 @lilypond[quote,ragged-right,verbatim]
1103 \new Staff \relative {
1106 { g4 f e | d2 e) | }
1111 { c8 b16 a b8 g~ 2 | }
1122 @cindex spacing notes
1124 This method of nesting new voices briefly is useful
1125 when only small sections of the music
1126 are polyphonic, but when the whole staff is largely polyphonic
1127 it can be clearer to use multiple voices throughout, using
1128 spacing notes to step over sections where the voice is silent,
1131 @lilypond[quote,ragged-right,verbatim]
1132 \new Staff \relative <<
1133 % Initiate first voice
1136 c'16^( d e f g4 f e | d2 e) |
1138 % Initiate second voice
1140 % Set stems, etc, down
1142 s4 r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
1144 % Initiate third voice
1146 % Set stems, etc, up
1153 @subsubheading Note columns
1156 @cindex note collisions
1157 @cindex collisions, notes
1158 @cindex shift commands
1162 @funindex \shiftOnnn
1164 Closely spaced notes in a chord, or notes occurring at the same
1165 time in different voices, are arranged in two, occasionally more,
1166 columns to prevent the note heads overlapping. These are called
1167 note columns. There are separate columns for each voice, and
1168 the currently specified voice-dependent shift is applied to the
1169 note column if there would otherwise be a collision. This can
1170 be seen in the example above. In bar 2 the C in voice two is
1171 shifted to the right relative to the D in voice one, and in the
1172 final chord the C in voice three is also shifted to the right
1173 relative to the other notes.
1175 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1176 @code{\shiftOff} commands specify the degree to which notes and
1177 chords of the voice should be shifted if a collision
1178 would otherwise occur. By default, the outer voices (normally
1179 voices one and two) have @code{\shiftOff} specified, while the
1180 inner voices (three and four) have @code{\shiftOn} specified.
1181 When a shift is applied, voices one and three are shifted to
1182 the right and voices two and four to the left.
1184 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1185 levels which may be specified temporarily to resolve collisions
1186 in complex situations -- see @ref{Real music example}.
1188 A note column can contain just one note (or chord) from a voice
1189 with stems up and one note (or chord) from a voice with stems
1190 down. If notes from two voices which have their stems in the
1191 same direction are placed at the same position and both voices
1192 have no shift or the same shift specified, the error message
1193 @qq{Too many clashing note columns} will be produced.
1197 Notation Reference: @ruser{Multiple voices}.
1200 @node Voices and vocals
1201 @subsection Voices and vocals
1203 Vocal music presents a special difficulty: we need to combine two
1204 expressions -- notes and lyrics.
1206 @funindex \new Lyrics
1209 @cindex Lyrics context, creating
1210 @cindex lyrics, linking to voice
1212 You have already seen the @code{\addlyrics@{@}} command, which
1213 handles simple scores well. However, this technique is
1214 quite limited. For more complex music, you must introduce the
1215 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1217 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1218 name assigned to the Voice.
1220 @lilypond[quote,verbatim]
1222 \new Voice = "one" {
1226 c''4 b8. a16 | g4. f8 | e4 d | c2 |
1229 \new Lyrics \lyricsto "one" {
1230 No more let | sins and | sor -- rows | grow. |
1235 Note that the lyrics must be linked to a @code{Voice} context,
1236 @emph{not} a @code{Staff} context. This is a case where it is
1237 necessary to create @code{Staff} and @code{Voice} contexts
1240 @cindex lyrics and beaming
1241 @cindex beaming and lyrics
1242 @funindex \autoBeamOff
1244 The automatic beaming which LilyPond uses by default works well
1245 for instrumental music, but not so well for music with lyrics,
1246 where beaming is either not required at all or is used to indicate
1247 melismata in the lyrics. In the example above we use the command
1248 @code{\autoBeamOff} to turn off the automatic beaming.
1250 @funindex \new ChoirStaff
1251 @funindex ChoirStaff
1252 @funindex \lyricmode
1253 @cindex vocal score structure
1256 Let us reuse the earlier example from Judas Maccabæus to
1257 illustrate this more flexible technique. We first recast
1258 it to use variables so the music and lyrics can be separated
1259 from the staff structure. We also introduce a ChoirStaff
1260 bracket. The lyrics themselves must be introduced with
1261 @code{\lyricmode} to ensure they are interpreted as lyrics
1264 @lilypond[quote,verbatim]
1265 global = { \key f \major \time 6/8 \partial 8 }
1267 SopOneMusic = \relative {
1268 c''8 | c8([ bes)] a a([ g)] f | f'4. b, | c4.~ 4
1270 SopOneLyrics = \lyricmode {
1271 Let | flee -- cy flocks the | hills a -- dorn, __
1273 SopTwoMusic = \relative {
1274 r8 | r4. r4 c'8 | a'8([ g)] f f([ e)] d | e8([ d)] c bes'
1276 SopTwoLyrics = \lyricmode {
1277 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{keyTime}, 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 keyTime = { \key c \major \time 4/4 \partial 4 }
1326 SopMusic = \relative { c'4 | e4. e8 g4 g | a4 a g }
1327 AltoMusic = \relative { c'4 | c4. c8 e4 e | f4 f e }
1328 TenorMusic = \relative { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1329 BassMusic = \relative { c4 | c4. c8 c4 c | f8 g a b c4 }
1332 \lyricmode { E -- | ter -- nal fa -- ther, | strong to save, }
1334 \lyricmode { O | Christ, whose voice the | wa -- ters heard, }
1336 \lyricmode { O | Ho -- ly Spi -- rit, | who didst brood }
1338 \lyricmode { O | Tri -- ni -- ty of | love and pow'r }
1344 \new Voice = "Sop" { \voiceOne \keyTime \SopMusic }
1345 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1346 \new Lyrics \lyricsto "Sop" { \VerseOne }
1347 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1348 \new Lyrics \lyricsto "Sop" { \VerseThree }
1349 \new Lyrics \lyricsto "Sop" { \VerseFour }
1353 \new Voice = "Tenor" { \voiceOne \keyTime \TenorMusic }
1354 \new Voice = "Bass" { \voiceTwo \BassMusic }
1362 Notation Reference: @ruser{Vocal music}.
1365 @node Contexts and engravers
1366 @section Contexts and engravers
1368 Contexts and engravers have been mentioned informally
1369 in earlier sections; we now must look at
1370 these concepts in more detail, as they are important
1371 in the fine-tuning of LilyPond output.
1375 * Contexts explained::
1376 * Creating contexts::
1377 * Engravers explained::
1378 * Modifying context properties::
1379 * Adding and removing engravers::
1382 @node Contexts explained
1383 @subsection Contexts explained
1385 @cindex contexts explained
1387 When music is printed, many notational elements which do not
1388 appear explicitly in the input file must be added to the
1389 output. For example, compare the input and output of the
1392 @lilypond[quote,verbatim]
1393 \relative { cis''4 cis2. | a4 a2. | }
1396 The input is rather sparse, but in the output, bar lines,
1397 accidentals, clef, and time signature have been added. When
1398 LilyPond @emph{interprets} the input the musical information
1399 is parsed from left to right, similar to the way a performer
1400 reads the score. While reading the input, the program remembers
1401 where measure boundaries are, and which pitches require explicit
1402 accidentals. This information must be held on several levels.
1403 For example, an accidental affects only a single staff, while
1404 a bar line must be synchronized across the entire score.
1406 Within LilyPond, these rules and bits of information are grouped in
1407 @emph{Contexts}. We have already introduced the @code{Voice} context.
1408 Others are the @code{Staff} and @code{Score} contexts. Contexts are
1409 hierarchical to reflect the hierarchical nature of a musical score.
1410 For example: a @code{Staff} context can contain many @code{Voice}
1411 contexts, and a @code{Score} context can contain many @code{Staff}
1415 @sourceimage{context-example,5cm,,}
1418 Each context has the responsibility for enforcing some notation rules,
1419 creating some notation objects and maintaining the associated
1420 properties. For example, the @code{Voice} context may introduce an
1421 accidental and then the @code{Staff} context maintains the rule to
1422 show or suppress the accidental for the remainder of the measure.
1424 As another example, the synchronization of bar lines is, by default,
1425 handled in the @code{Score} context.
1426 However, in some music we may not want the bar lines to be
1427 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1428 In such cases, we must modify the default settings of the
1429 @code{Score} and @code{Staff} contexts.
1431 For very simple scores, contexts are created implicitly, and you need
1432 not be aware of them. For larger pieces, such as anything with more
1433 than one staff, they must be
1434 created explicitly to make sure that you get as many staves as you
1435 need, and that they are in the correct order. For typesetting pieces
1436 with specialized notation, it is usual to modify existing, or
1437 even to define totally new, contexts.
1439 In addition to the @code{Score,} @code{Staff} and
1440 @code{Voice} contexts there are contexts which fit between
1441 the score and staff levels to control staff groups, such as the
1442 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1443 are also alternative staff and voice contexts, and contexts for
1444 lyrics, percussion, fret boards, figured bass, etc.
1446 The names of all context types are formed from one or more
1447 words, each word being capitalized and joined immediately to the
1448 preceding word with no hyphen or underscore, e.g.,
1449 @code{GregorianTranscriptionStaff}.
1453 Notation Reference: @ruser{Contexts explained}.
1456 @node Creating contexts
1457 @subsection Creating contexts
1460 @cindex new contexts
1461 @cindex creating contexts
1462 @cindex contexts, creating
1464 In an input file a score block, introduced with a @code{\score}
1465 command, contains a single music expression and an associated
1466 output definition (either a @code{\layout} or a @code{\midi} block).
1467 The @code{Score} context is usually left to be created automatically
1468 when the interpretation of that music expression starts.
1470 For scores with only one voice and one staff, the @code{Voice} and
1471 @code{Staff} contexts may also be left to be created automatically,
1472 but for more complex scores it is necessary to create them by hand.
1473 The simplest command that does this is @code{\new}. It is prepended
1474 to a music expression, for example
1477 \new @var{type} @var{music-expression}
1481 where @var{type} is a context name (like @code{Staff} or
1482 @code{Voice}). This command creates a new context, and starts
1483 interpreting the @var{music-expression} within that context.
1485 @warning{@bs{}@code{new Score} should not be used as the essential
1486 top-level @code{Score} context is created automatically when the music
1487 expression within the @bs{}@code{score} block is interpreted. Score-wide
1488 default values of context properties can be changed within the
1489 @bs{}@code{layout} block. See @ref{Modifying context properties}}
1491 You have seen many practical examples which created new
1492 @code{Staff} and @code{Voice} contexts in earlier sections, but
1493 to remind you how these commands are used in practice, here's an
1494 annotated real-music example:
1496 @lilypond[quote,verbatim,ragged-right]
1497 \score { % start of single compound music expression
1498 << % start of simultaneous staves section
1500 \new Staff { % create RH staff
1503 \new Voice { % create voice for RH notes
1504 \relative { % start of RH notes
1510 \new Staff << % create LH staff; needs two simultaneous voices
1513 \new Voice { % create LH voice one
1515 \relative { % start of LH voice one notes
1516 g8 <bes d> ees, <g c> |
1517 g8 <bes d> ees, <g c> |
1518 } % end of LH voice one notes
1519 } % end of LH voice one
1520 \new Voice { % create LH voice two
1522 \relative { % start of LH voice two notes
1525 } % end of LH voice two notes
1526 } % end of LH voice two
1527 >> % end of LH staff
1528 >> % end of simultaneous staves section
1529 } % end of single compound music expression
1532 (Note how all the statements which open a block with either a
1533 curly bracket, @code{@{}, or double angle brackets, @code{<<},
1534 are indented by two further spaces, and the corresponding
1535 closing bracket is indented by exactly the same amount. While
1536 this is not required, following this practice will greatly
1537 reduce the number of @q{unmatched bracket} errors, and is
1538 strongly recommended. It enables the structure of the music to
1539 be seen at a glance, and any unmatched brackets will be obvious.
1540 Note too how the LH staff is created using double angle brackets
1541 because it requires two voices for its music, whereas the RH staff
1542 is created with a single music expression surrounded by curly
1543 brackets because it requires only one voice.)
1545 @cindex contexts, naming
1546 @cindex naming contexts
1548 The @code{\new} command may also give an identifying name to the
1549 context to distinguish it from other contexts of the same type,
1552 \new @var{type} = @var{id} @var{music-expression}
1555 Note the distinction between the name of the context type,
1556 @code{Staff}, @code{Voice}, etc, and the identifying name of a
1557 particular instance of that type, which can be any sequence of letters
1558 invented by the user. Digits and spaces can also be used in the
1559 identifying name, but then it has to be placed in quotes,
1560 i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
1561 The identifying name is used to
1562 refer back to that particular instance of a context. We saw this in
1563 use in the section on lyrics, see @ref{Voices and vocals}.
1567 Notation Reference: @ruser{Creating contexts}.
1570 @node Engravers explained
1571 @subsection Engravers explained
1575 Every mark on the printed output of a score produced by LilyPond
1576 is produced by an @code{Engraver}. Thus there is an engraver
1577 to print staves, one to print note heads, one for stems, one for
1578 beams, etc, etc. In total there are over 120 such engravers!
1579 Fortunately, for most scores it is not necessary to know about
1580 more than a few, and for simple scores you do not need to know
1583 Engravers live and operate in Contexts. Engravers such as the
1584 @code{Metronome_mark_engraver}, whose action and output apply to the
1585 score as a whole, operate in the highest level context -- the
1586 @code{Score} context.
1588 The @code{Clef_engraver} and @code{Key_engraver} are to be
1589 found in every @code{Staff} Context, as different staves may require
1590 different clefs and keys.
1592 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1593 in every @code{Voice} context, the lowest level context of all.
1595 Each engraver processes the particular objects associated
1596 with its function, and maintains the properties that relate
1597 to that function. These properties, like the properties
1598 associated with contexts, may be modified to change the
1599 operation of the engraver or the appearance of those elements
1600 in the printed score.
1602 Engravers all have compound names formed from words which
1603 describe their function. Just the first word is capitalized,
1604 and the remainder are joined to it with underscores. Thus
1605 the @code{Staff_symbol_engraver} is responsible for creating the
1606 lines of the staff, the @code{Clef_engraver} determines and sets
1607 the pitch reference point on the staff by drawing a clef symbol.
1609 Here are some of the most common engravers together with their
1610 function. You will see it is usually easy to guess the function
1611 from the name, or vice versa.
1613 @multitable @columnfractions .3 .7
1616 @item Accidental_engraver
1617 @tab Makes accidentals, cautionary and suggested accidentals
1622 @item Completion_heads_engraver
1623 @tab Splits notes which cross bar lines
1624 @item Dynamic_engraver
1625 @tab Creates hairpins and dynamic texts
1626 @item Forbid_line_break_engraver
1627 @tab Prevents line breaks if a musical element is still active
1629 @tab Creates the key signature
1630 @item Metronome_mark_engraver
1631 @tab Engraves metronome marking
1632 @item Note_heads_engraver
1633 @tab Engraves note heads
1636 @item Staff_symbol_engraver
1637 @tab Engraves the five (by default) lines of the staff
1639 @tab Creates stems and single-stem tremolos
1640 @item Time_signature_engraver
1641 @tab Creates time signatures
1646 We shall see later how the output of LilyPond can be changed
1647 by modifying the action of Engravers.
1651 Internals reference: @rinternals{Engravers and Performers}.
1654 @node Modifying context properties
1655 @subsection Modifying context properties
1657 @cindex context properties
1658 @cindex context properties, modifying
1659 @cindex modifying context properties
1663 Contexts are responsible for holding the values of a number of
1664 context @emph{properties}. Many of them can be changed to
1665 influence the interpretation of the input and so change the
1666 appearance of the output. They are changed by the
1667 @code{\set} command. This takes the form
1670 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1673 Where the @emph{ContextName} is usually @code{Score},
1674 @code{Staff} or @code{Voice}. It may be omitted,
1675 in which case the current context (typically @code{Voice}) is assumed.
1677 The names of context properties consist of words joined
1678 together with no hyphens or underscores, all except the
1679 first having a capital letter. Here are a few examples
1680 of some commonly used ones. There are many more.
1682 @c attempt to force this onto a new page
1684 @multitable @columnfractions .25 .15 .45 .15
1685 @headitem propertyName
1691 @tab If true, set extra natural signs before accidentals
1692 @tab @code{#t}, @code{#f}
1693 @item currentBarNumber
1695 @tab Set the current bar number
1699 @tab If true, print slurs both above and below notes
1700 @tab @code{#t}, @code{#f}
1701 @item instrumentName
1703 @tab Set the name to be placed at the start of the staff
1704 @tab @code{"Cello I"}
1707 @tab Increase or decrease the font size
1711 @tab Set the text to print before the start of a verse
1716 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1717 an Integer is a positive whole number, a Real is a positive
1718 or negative decimal number, and text is enclosed in double
1719 apostrophes. Note the occurrence of hash signs,
1720 (@code{#}), in two different places -- as part of the Boolean
1721 value before the @code{t} or @code{f}, and before @emph{value}
1722 in the @code{\set} statement. So when a Boolean is being
1723 entered you need to code two hash signs, e.g., @code{##t}.
1725 @cindex properties operating in contexts
1726 @cindex setting properties within contexts
1728 Before we can set any of these properties we need to know
1729 in which context they operate. Sometimes this is obvious,
1730 but occasionally it can be tricky. If the wrong context
1731 is specified, no error message is produced, but the expected
1732 action will not take place. For example, the
1733 @code{instrumentName} clearly lives in the @code{Staff} context, since
1734 it is the staff that is to be named.
1735 In this example the first staff is labeled, but not the second,
1736 because we omitted the context name.
1738 @lilypond[quote,verbatim,ragged-right]
1740 \new Staff \relative {
1741 \set Staff.instrumentName = #"Soprano"
1744 \new Staff \relative {
1745 \set instrumentName = #"Alto" % Wrong!
1751 Remember the default context name is @code{Voice}, so the second
1752 @code{\set} command set the property @code{instrumentName} in the
1753 @code{Voice} context to @qq{Alto}, but as LilyPond does not look
1754 for any such property in the @code{Voice} context, no
1755 further action took place. This is not an error, and no error
1756 message is logged in the log file.
1758 Similarly, if the property name is mis-spelt no error message is
1759 produced, and clearly the expected action cannot be performed. In
1760 fact, you can set any (fictitious) @q{property} using any name you
1761 like in any context that exists by using the @code{\set} command. But
1762 if the name is not known to LilyPond it will not cause any action to
1763 be taken. Some text editors with special support for LilyPond input
1764 files document property names with bullets when you hover them with
1765 the mouse, like JEdit with LilyPondTool, or highlight unknown property
1766 names differently, like ConTEXT. If you do not use an editor with
1767 such features, it is recommended to check the property name in the
1768 Internals Reference: see @rinternals{Tunable context properties}, or
1769 @rinternals{Contexts}.
1771 The @code{instrumentName} property will take effect only
1772 if it is set in the @code{Staff} context, but
1773 some properties can be set in more than one context.
1774 For example, the property @code{extraNatural} is by
1775 default set to ##t (true) for all staves.
1776 If it is set to ##f (false) in one particular @code{Staff}
1777 context it applies just to the accidentals on that staff.
1778 If it is set to false in the @code{Score} context
1779 it applies to all staves.
1781 So this turns off extra naturals in one staff:
1783 @lilypond[quote,verbatim,ragged-right]
1785 \new Staff \relative {
1788 \new Staff \relative {
1789 \set Staff.extraNatural = ##f
1796 and this turns them off in all staves:
1798 @lilypond[quote,verbatim,ragged-right]
1800 \new Staff \relative {
1803 \new Staff \relative {
1804 \set Score.extraNatural = ##f
1810 As another example, if @code{clefTransposition} is set in
1811 the @code{Score} context this immediately changes the value
1812 of the transposition in all current staves and sets a new default
1813 value which will be applied to all staves.
1815 The opposite command, @code{\unset}, effectively removes the
1816 property from the context, which causes most properties to
1817 revert to their default value. Usually @code{\unset} is not
1818 required as a new @code{\set} command will achieve what is
1821 The @code{\set} and @code{\unset} commands can appear anywhere
1822 in the input file and will take effect from the time they are
1823 encountered until the end of the score or until the property is
1824 @code{\set} or @code{\unset} again. Let's try changing the
1825 font size, which affects the size of the note heads (among
1826 other things) several times. The change is from the default
1827 value, not the most recently set value.
1829 @lilypond[quote,verbatim,ragged-right]
1832 % make note heads smaller
1835 % make note heads larger
1836 \set fontSize = #2.5
1838 % return to default size
1844 We have now seen how to set the values of several different types of
1845 property. Note that integers and numbers are always preceded by a
1846 hash sign, @code{#}, while a true or false value is specified by
1847 @code{##t} and @code{##f}, with two hash signs. A text property
1848 should be enclosed in double quotation signs, as above, although we
1849 shall see later that text can actually be specified in a much more
1850 general way by using the very powerful @code{\markup} command.
1852 @subsubheading Setting context properties with @code{\with}
1855 @cindex context properties, setting with \with
1857 The default value of context properties may be set at the time the
1858 context is created. Sometimes this is a clearer way of setting a
1859 property value if it is to remain fixed for the duration of
1860 the context. When a context is created with a @code{\new}
1861 command it may be followed immediately by a @code{\with @{ .. @}}
1862 block in which the default property values are set. For example,
1863 if we wish to suppress the printing of extra naturals for the
1864 duration of a staff we would write:
1867 \new Staff \with @{ extraNatural = ##f @}
1873 @lilypond[quote,verbatim,ragged-right]
1877 gisis'4 gis aeses aes
1880 \new Staff \with { extraNatural = ##f } {
1882 gisis'4 gis aeses aes
1888 Properties set in this way may still be changed dynamically using
1889 @code{\set} and returned to the default value set in the
1890 @code{\with} block with @code{\unset}.
1892 @cindex fontSize, default and setting
1894 So if the @code{fontSize} property is set in a @code{\with} clause
1895 it sets the default value of the font size. If it is later changed
1896 with @code{\set}, this new default value may be restored with the
1897 @code{\unset fontSize} command.
1899 @subsubheading Setting context properties with @code{\context}
1901 @cindex context properties, setting with \context
1904 The values of context properties may be set in @emph{all} contexts
1905 of a particular type, such as all @code{Staff} contexts, with a single
1906 command. The context type is identified by using its
1907 type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
1908 The statement which sets the property value is the same as that in a
1909 @code{\with} block, introduced above. It is placed in a
1910 @code{\context} block within a @code{\layout} block. Each
1911 @code{\context} block will affect all contexts of the type specified
1912 throughout the @code{\score} or @code{\book} block in which the
1913 @code{\layout} block appears. Here is an example to show the format:
1915 @lilypond[verbatim,quote]
1931 If the property override is to be applied to all staves
1934 @lilypond[quote,verbatim]
1939 gisis'4 gis aeses aes
1944 gisis'4 gis aeses aes
1950 \Score extraNatural = ##f
1957 Context properties set in this way may be overridden for particular
1958 instances of contexts by statements in a @code{\with} block, and by
1959 @code{\set} commands embedded in music statements.
1964 @ruser{Changing context default settings}.
1965 @ruser{The set command}.
1967 Internals Reference:
1968 @rinternals{Contexts},
1969 @rinternals{Tunable context properties}.
1972 @node Adding and removing engravers
1973 @subsection Adding and removing engravers
1975 @cindex engravers, adding
1976 @cindex adding engravers
1977 @cindex engravers, removing
1978 @cindex removing engravers
1983 We have seen that contexts each contain several engravers, each
1984 of which is responsible for producing a particular part of the
1985 output, like bar lines, staves, note heads, stems, etc. If an
1986 engraver is removed from a context, it can no longer produce its
1987 output. This is a crude way of modifying the output, but it
1988 can sometimes be useful.
1990 @subsubheading Changing a single context
1992 To remove an engraver from a single context we use the
1993 @code{\with} command placed immediately after the context creation
1994 command, as in the previous section.
1996 As an illustration, let's repeat an example from the previous section
1997 with the staff lines removed. Remember that the staff lines are
1998 produced by the @code{Staff_symbol_engraver}.
2000 @lilypond[quote,verbatim,ragged-right]
2002 \remove "Staff_symbol_engraver"
2006 \set fontSize = #-4 % make note heads smaller
2008 \set fontSize = #2.5 % make note heads larger
2010 \unset fontSize % return to default size
2015 @cindex ambitus engraver
2017 Engravers can also be added to individual contexts.
2018 The command to do this is
2020 @code{\consists @var{Engraver_name}},
2023 placed inside a @code{\with} block. Some vocal scores have an ambitus
2024 placed at the beginning of a staff to indicate the range of notes in
2025 that staff -- see @rglos{ambitus}. The ambitus is produced by the
2026 @code{Ambitus_engraver}, which is not normally included in any
2027 context. If we add it to the @code{Voice} context, it calculates the
2028 range from that voice only:
2030 @lilypond[quote,verbatim,ragged-right]
2033 \consists "Ambitus_engraver"
2050 but if we add the ambitus engraver to the
2051 @code{Staff} context, it calculates the range from all
2052 the notes in all the voices on that staff:
2054 @lilypond[quote,verbatim,ragged-right]
2056 \consists "Ambitus_engraver"
2074 @subsubheading Changing all contexts of the same type
2078 The examples above show how to remove or add engravers to
2079 individual contexts. It is also possible to remove or add
2080 engravers to every context of a specific type by placing the
2081 commands in the appropriate context in a @code{\layout}
2082 block. For example, if we wanted to show an ambitus for every
2083 staff in a four-staff score, we could write
2085 @lilypond[quote,verbatim,ragged-right]
2114 \consists "Ambitus_engraver"
2121 The values of context properties may also be set
2122 for all contexts of a particular type by including the
2123 @code{\set} command in a @code{\context} block in the
2127 Notation Reference: @ruser{Modifying context plug-ins},
2128 @ruser{Changing context default settings}.
2131 The @code{Stem_engraver} and @code{Beam_engraver} attach their
2132 objects to note heads. If the @code{Note_heads_engraver} is removed
2133 no note heads are produced and therefore no stems or beams are created
2137 @node Extending the templates
2138 @section Extending the templates
2140 You've read the tutorial, you know how to write music, you
2141 understand the fundamental concepts. But how can you
2142 get the staves that you want? Well, you can find lots of
2143 templates (see @ref{Templates}) which may give you a start.
2144 But what if you want something that isn't covered there? Read on.
2147 * Soprano and cello::
2148 * Four-part SATB vocal score::
2149 * Building a score from scratch::
2150 * Saving typing with variables and functions::
2151 * Scores and parts::
2154 @node Soprano and cello
2155 @subsection Soprano and cello
2157 @cindex template, modifying
2158 @cindex modifying templates
2160 Start off with the template that seems closest to what you want to
2161 end up with. Let's say that you want to write something for
2162 soprano and cello. In this case, we would start with the
2163 @q{Notes and lyrics} template (for the soprano part).
2166 \version @w{"@version{}"}
2168 melody = \relative @{
2175 text = \lyricmode @{
2181 \new Voice = "one" @{
2185 \new Lyrics \lyricsto "one" \text
2192 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2195 \version @w{"@version{}"}
2197 melody = \relative @{
2211 We don't need two @code{\version} commands. We'll need the
2212 @code{melody} section. We don't want two @code{\score} sections
2213 -- if we had two @code{\score}s, we'd get the two parts separately.
2214 We want them together, as a duet. Within the @code{\score}
2215 section, we don't need two @code{\layout} or @code{\midi}.
2217 If we simply cut and paste the @code{melody} section, we would
2218 end up with two @code{melody} definitions. This would not generate
2219 an error, but the second one would be used for both melodies.
2220 So let's rename them to make them distinct. We'll call the
2221 section for the soprano @code{sopranoMusic} and the section for
2222 the cello @code{celloMusic}. While we're doing this, let's rename
2223 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2224 instances of all these names -- both the initial definition (the
2225 @code{melody = \relative c' @{ } part) and the name's use (in the
2226 @code{\score} section).
2228 While we're doing this, let's change the cello part's staff --
2229 celli normally use bass clef. We'll also give the cello some
2233 \version @w{"@version{}"}
2235 sopranoMusic = \relative @{
2242 sopranoLyrics = \lyricmode @{
2246 celloMusic = \relative @{
2255 \new Voice = "one" @{
2259 \new Lyrics \lyricsto "one" \sopranoLyrics
2266 This is looking promising, but the cello part won't appear in the
2267 score -- we haven't used it in the @code{\score} section. If we
2268 want the cello part to appear under the soprano part, we need to add
2271 \new Staff \celloMusic
2275 underneath the soprano stuff. We also need to add @code{<<} and
2276 @code{>>} around the music -- that tells LilyPond that there's
2277 more than one thing (in this case, two @code{Staves}) happening
2278 at once. The @code{\score} looks like this now:
2280 @c Indentation in this example is deliberately poor
2285 \new Voice = "one" @{
2289 \new Lyrics \lyricsto "one" \sopranoLyrics
2291 \new Staff \celloMusic
2299 This looks a bit messy; the indentation is messed up now. That is
2300 easily fixed. Here's the complete soprano and cello template.
2302 @lilypond[quote,verbatim,ragged-right,addversion]
2303 sopranoMusic = \relative {
2310 sopranoLyrics = \lyricmode {
2314 celloMusic = \relative {
2324 \new Voice = "one" {
2328 \new Lyrics \lyricsto "one" \sopranoLyrics
2330 \new Staff \celloMusic
2339 The starting templates can be found in the @q{Templates} appendix,
2340 see @ref{Single staff templates}.
2343 @node Four-part SATB vocal score
2344 @subsection Four-part SATB vocal score
2346 @cindex template, SATB
2347 @cindex SATB template
2349 Most vocal scores of music written for four-part mixed choir
2350 with orchestral accompaniment such as Mendelssohn's Elijah or
2351 Handel's Messiah have the choral music and words on four
2352 staves, one for each of SATB, with a piano reduction of the
2353 orchestral accompaniment underneath. Here's an example
2354 from Handel's Messiah:
2356 @c The following should appear as music without code
2357 @lilypond[quote,ragged-right]
2358 global = { \key d \major \time 4/4 }
2360 sopranoMusic = \relative {
2362 r4 d''2 a4 | d4. d8 a2 | cis4 d cis2 |
2364 sopranoWords = \lyricmode {
2365 Wor -- thy | is the lamb | that was slain |
2368 altoMusic = \relative {
2370 r4 a'2 a4 | fis4. fis8 a2 | g4 fis e2 |
2372 altoWords = \sopranoWords
2374 tenorMusic = \relative {
2376 r4 fis'2 e4 | d4. d8 d2 | e4 a, cis2 |
2378 tenorWords = \sopranoWords
2380 bassMusic = \relative {
2382 r4 d'2 cis4 | b4. b8 fis2 | e4 d a'2 |
2384 bassWords = \sopranoWords
2389 r4 <a' d fis>2 <a e' a>4 |
2390 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2391 <g cis g'>4 <a d fis> <a cis e>2 |
2397 <d, d'>4 <d d'>2 <cis cis'>4 |
2398 <b b'>4. <b' b'>8 <fis fis'>2 |
2399 <e e'>4 <d d'> <a' a'>2 |
2403 << % combine ChoirStaff and PianoStaff in parallel
2405 \new Staff = "sopranos" <<
2406 \set Staff.instrumentName = #"Soprano"
2407 \new Voice = "sopranos" {
2412 \new Lyrics \lyricsto "sopranos" {
2415 \new Staff = "altos" <<
2416 \set Staff.instrumentName = #"Alto"
2417 \new Voice = "altos" {
2422 \new Lyrics \lyricsto "altos" { \altoWords }
2423 \new Staff = "tenors" <<
2424 \set Staff.instrumentName = #"Tenor"
2425 \new Voice = "tenors" {
2430 \new Lyrics \lyricsto "tenors" { \tenorWords }
2431 \new Staff = "basses" <<
2432 \set Staff.instrumentName = #"Bass"
2433 \new Voice = "basses" {
2438 \new Lyrics \lyricsto "basses" {
2443 \set PianoStaff.instrumentName = #"Piano"
2444 \new Staff = "upper" \upper
2445 \new Staff = "lower" \lower
2451 None of the templates provides this layout exactly. The nearest is
2452 @ref{SATB vocal score and automatic piano reduction} -- but we need
2453 to change the layout and add a piano
2454 accompaniment which is not derived automatically from the vocal parts.
2455 The variables holding the music and words for the vocal parts are
2456 fine, but we shall need to add variables for the piano reduction.
2458 The order in which the contexts appear in the ChoirStaff of the
2459 template do not correspond with the order in the vocal score shown
2460 above. We need to rearrange them so there are four staves with the
2461 words written directly underneath the notes for each part. All the
2462 voices should be @code{\voiceOne}, which is the default, so the
2463 @code{\voiceXXX} commands should be removed. We also need to specify
2464 the tenor clef for the tenors. The way in which lyrics are specified
2465 in the template has not yet been encountered so we need to use the
2466 method with which we are familiar. We should also add the names of
2469 Doing this gives for our ChoirStaff:
2473 \new Staff = "sopranos" <<
2474 \set Staff.instrumentName = #"Soprano"
2475 \new Voice = "sopranos" @{
2480 \new Lyrics \lyricsto "sopranos" @{
2483 \new Staff = "altos" <<
2484 \set Staff.instrumentName = #"Alto"
2485 \new Voice = "altos" @{
2490 \new Lyrics \lyricsto "altos" @{
2493 \new Staff = "tenors" <<
2494 \set Staff.instrumentName = #"Tenor"
2495 \new Voice = "tenors" @{
2500 \new Lyrics \lyricsto "tenors" @{
2503 \new Staff = "basses" <<
2504 \set Staff.instrumentName = #"Bass"
2505 \new Voice = "basses" @{
2510 \new Lyrics \lyricsto "basses" @{
2516 Next we must work out the piano part. This is
2517 easy - we just pull out the piano part from the
2518 @q{Solo piano} template:
2522 \set PianoStaff.instrumentName = #"Piano "
2523 \new Staff = "upper" \upper
2524 \new Staff = "lower" \lower
2528 and add the variable definitions for @code{upper}
2531 The ChoirStaff and PianoStaff must be combined
2532 using angle brackets as we want them to be
2533 stacked one above the other:
2536 << % combine ChoirStaff and PianoStaff one above the other
2538 \new Staff = "sopranos" <<
2539 \new Voice = "sopranos" @{
2544 \new Lyrics \lyricsto "sopranos" @{
2547 \new Staff = "altos" <<
2548 \new Voice = "altos" @{
2553 \new Lyrics \lyricsto "altos" @{
2556 \new Staff = "tenors" <<
2557 \clef "G_8" % tenor clef
2558 \new Voice = "tenors" @{
2563 \new Lyrics \lyricsto "tenors" @{
2566 \new Staff = "basses" <<
2568 \new Voice = "basses" @{
2573 \new Lyrics \lyricsto "basses" @{
2579 \set PianoStaff.instrumentName = #"Piano"
2580 \new Staff = "upper" \upper
2581 \new Staff = "lower" \lower
2586 Combining all these together and adding the music
2587 for the three bars of the example above gives:
2589 @lilypond[quote,verbatim,ragged-right,addversion]
2590 global = { \key d \major \time 4/4 }
2591 sopranoMusic = \relative {
2593 r4 d''2 a4 | d4. d8 a2 | cis4 d cis2 |
2595 sopranoWords = \lyricmode {
2596 Wor -- thy | is the lamb | that was slain |
2598 altoMusic = \relative {
2600 r4 a'2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2602 altoWords = \sopranoWords
2603 tenorMusic = \relative {
2605 r4 fis'2 e4 | d4. d8 d2 | e4 a, cis2 |
2607 tenorWords = \sopranoWords
2608 bassMusic = \relative {
2610 r4 d'2 cis4 | b4. b8 fis2 | e4 d a'2 |
2612 bassWords = \sopranoWords
2616 r4 <a' d fis>2 <a e' a>4 |
2617 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2618 <g cis g'>4 <a d fis> <a cis e>2 |
2623 <d, d'>4 <d d'>2 <cis cis'>4 |
2624 <b b'>4. <b' b'>8 <fis fis'>2 |
2625 <e e'>4 <d d'> <a' a'>2 |
2629 << % combine ChoirStaff and PianoStaff in parallel
2631 \new Staff = "sopranos" <<
2632 \set Staff.instrumentName = #"Soprano"
2633 \new Voice = "sopranos" {
2638 \new Lyrics \lyricsto "sopranos" {
2641 \new Staff = "altos" <<
2642 \set Staff.instrumentName = #"Alto"
2643 \new Voice = "altos" {
2648 \new Lyrics \lyricsto "altos" {
2651 \new Staff = "tenors" <<
2652 \set Staff.instrumentName = #"Tenor"
2653 \new Voice = "tenors" {
2658 \new Lyrics \lyricsto "tenors" {
2661 \new Staff = "basses" <<
2662 \set Staff.instrumentName = #"Bass"
2663 \new Voice = "basses" {
2668 \new Lyrics \lyricsto "basses" {
2674 \set PianoStaff.instrumentName = #"Piano "
2675 \new Staff = "upper" \upper
2676 \new Staff = "lower" \lower
2683 @node Building a score from scratch
2684 @subsection Building a score from scratch
2686 @cindex template, writing your own
2687 @cindex example of writing a score
2688 @cindex writing a score, example
2689 @cindex score, example of writing
2691 After gaining some facility with writing LilyPond code, you
2692 may find that it is easier to build a score from scratch
2693 rather than modifying one of the templates. You can also
2694 develop your own style this way to suit the sort of music you
2695 like. Let's see how to put together the score for an organ
2696 prelude as an example.
2698 We begin with a header section. Here go the title, name
2699 of composer, etc, then come any variable definitions, and
2700 finally the score block. Let's start with these in outline
2701 and fill in the details later.
2703 We'll use the first two bars of Bach's prelude
2704 based on @emph{Jesu, meine Freude} which is written for two
2705 manuals and pedal organ. You can see these two bars of music
2706 at the bottom of this section. The top manual part has two voices,
2707 the lower and pedal organ one each. So we need four
2708 music definitions and one to define the time signature
2712 \version @w{"@version{}"}
2714 title = "Jesu, meine Freude"
2715 composer = "J S Bach"
2717 keyTime = @{ \key c \minor \time 4/4 @}
2718 ManualOneVoiceOneMusic = @{ s1 @}
2719 ManualOneVoiceTwoMusic = @{ s1 @}
2720 ManualTwoMusic = @{ s1 @}
2721 PedalOrganMusic = @{ s1 @}
2727 For now we've just used a spacer note, @code{s1},
2728 instead of the real music. We'll add that later.
2730 Next let's see what should go in the score block.
2731 We simply mirror the staff structure we want.
2732 Organ music is usually written on three staves,
2733 one for each manual and one for the pedals. The
2734 manual staves should be bracketed together, so we
2735 need to use a PianoStaff for them. The first
2736 manual part needs two voices and the second manual
2741 \new Staff = "ManualOne" <<
2743 \ManualOneVoiceOneMusic
2746 \ManualOneVoiceTwoMusic
2748 >> % end ManualOne Staff context
2749 \new Staff = "ManualTwo" <<
2753 >> % end ManualTwo Staff context
2754 >> % end PianoStaff context
2757 Next we need to add a staff for the pedal organ.
2758 This goes underneath the PianoStaff, but it must
2759 be simultaneous with it, so we need angle brackets
2760 around the two. Missing these out would generate
2761 an error in the log file. It's a common mistake
2762 which you'll make sooner or later! Try copying
2763 the final example at the end of this section,
2764 remove these angle brackets, and compile it to
2765 see what errors it generates.
2768 << % PianoStaff and Pedal Staff must be simultaneous
2770 \new Staff = "ManualOne" <<
2772 \ManualOneVoiceOneMusic
2775 \ManualOneVoiceTwoMusic
2777 >> % end ManualOne Staff context
2778 \new Staff = "ManualTwo" <<
2782 >> % end ManualTwo Staff context
2783 >> % end PianoStaff context
2784 \new Staff = "PedalOrgan" <<
2792 It is not necessary to use the simultaneous construct
2793 @code{<< .. >>} for the manual two staff and the pedal organ staff,
2794 since they contain only one music expression, but it does no harm,
2795 and always using angle brackets after @code{\new Staff} is a good
2796 habit to cultivate in case there are multiple voices. The opposite
2797 is true for Voices: these should habitually be followed by braces
2798 @code{@{ .. @}} in case your music is coded in several variables
2799 which need to run consecutively.
2801 Let's add this structure to the score block, and adjust the indenting.
2802 We also add the appropriate clefs, ensure stems, ties and slurs in
2803 each voice on the upper staff point to the right direction with
2804 @code{\voiceOne} and @code{\voiceTwo}, and enter the key and time
2805 signature to each staff using our predefined variable, @code{\keyTime}.
2809 << % PianoStaff and Pedal Staff must be simultaneous
2811 \new Staff = "ManualOne" <<
2812 \keyTime % set key and time signature
2816 \ManualOneVoiceOneMusic
2820 \ManualOneVoiceTwoMusic
2822 >> % end ManualOne Staff context
2823 \new Staff = "ManualTwo" <<
2829 >> % end ManualTwo Staff context
2830 >> % end PianoStaff context
2831 \new Staff = "PedalOrgan" <<
2837 >> % end PedalOrgan Staff
2839 @} % end Score context
2842 @cindex stretchability of staves
2843 @cindex staves, stretchability
2845 The above layout of the organ staves is almost perfect; however,
2846 there is a slight defect which is not visible by looking at just a
2847 single system: The distance of the pedal staff to the left hand staff
2848 should behave approximately the same as the right hand staff to the
2849 left hand staff. In particular, the stretchability of staves in a
2850 @code{PianoStaff} context is limited (so that the distance between
2851 the staves for the left and right hand can't become too large), and
2852 the pedal staff should behave similarly.
2854 @cindex sub-properties
2855 @cindex properties, sub-properties
2856 @cindex graphical objects
2857 @cindex objects, graphical
2860 Stretchability of staves can be controlled with the
2861 @code{staff-staff-spacing} property of the
2862 @code{VerticalAxisGroup} @q{graphical object} (commonly called
2863 @q{grob}s within the lilypond documentation) -- don't worry about
2864 the details right now; this is fully explained later. For the
2865 curious, have a look at @ruser{Overview of modifying properties}.
2866 In this case, we want to modify the @code{stretchability}
2867 sub-property only. Again, for the curious, you can find the
2868 default values for the staff-staff-spacing property
2869 in file @file{scm/define-grobs.scm} by looking up the definition
2870 of the @code{VerticalAxisGroup} grob. The value for
2871 @code{stretchability} is taken from the definition of the
2872 @code{PianoStaff} context (in file @file{ly/engraver-init.ly})
2873 so that the values are identical.
2877 << % PianoStaff and Pedal Staff must be simultaneous
2879 \new Staff = "ManualOne" <<
2880 \keyTime % set key and time signature
2884 \ManualOneVoiceOneMusic
2888 \ManualOneVoiceTwoMusic
2890 >> % end ManualOne Staff context
2891 \new Staff = "ManualTwo" \with @{
2892 \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
2899 >> % end ManualTwo Staff context
2900 >> % end PianoStaff context
2901 \new Staff = "PedalOrgan" <<
2907 >> % end PedalOrgan Staff
2909 @} % end Score context
2911 That completes the structure. Any three-staff organ music
2912 will have a similar structure, although the number of voices
2913 may vary. All that remains now
2914 is to add the music, and combine all the parts together.
2916 @lilypond[quote,verbatim,ragged-right,addversion]
2918 title = "Jesu, meine Freude"
2919 composer = "J S Bach"
2921 keyTime = { \key c \minor \time 4/4 }
2922 ManualOneVoiceOneMusic = \relative {
2926 ManualOneVoiceTwoMusic = \relative {
2927 ees'16 d ees8~ 16 f ees d c8 d~ d c~ |
2928 8 c4 b8 c8. g16 c b c d |
2930 ManualTwoMusic = \relative {
2931 c'16 b c8~ 16 b c g a8 g~ 16 g aes ees |
2932 f16 ees f d g aes g f ees d ees8~ 16 f ees d |
2934 PedalOrganMusic = \relative {
2935 r8 c16 d ees d ees8~ 16 a, b g c b c8 |
2936 r16 g ees f g f g8 c,2 |
2940 << % PianoStaff and Pedal Staff must be simultaneous
2942 \new Staff = "ManualOne" <<
2943 \keyTime % set key and time signature
2947 \ManualOneVoiceOneMusic
2951 \ManualOneVoiceTwoMusic
2953 >> % end ManualOne Staff context
2954 \new Staff = "ManualTwo" \with {
2955 \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
2962 >> % end ManualTwo Staff context
2963 >> % end PianoStaff context
2964 \new Staff = "PedalOrgan" <<
2970 >> % end PedalOrgan Staff context
2972 } % end Score context
2979 @node Saving typing with variables and functions
2980 @subsection Saving typing with variables and functions
2985 By this point, you've seen this kind of thing:
2987 @lilypond[quote,verbatim,ragged-right]
2988 hornNotes = \relative { c''4 b dis c }
2997 You may even realize that this could be useful in minimalist music:
2999 @lilypond[quote,verbatim,ragged-right]
3000 fragmentA = \relative { a'4 a8. b16 }
3001 fragmentB = \relative { a'8. gis16 ees4 }
3003 violin = \new Staff {
3004 \fragmentA \fragmentA |
3005 \fragmentB \fragmentA |
3015 However, you can also use these variables (also known as
3016 macros, or user-defined commands) for tweaks:
3018 @c TODO Avoid padtext - not needed with skylining
3019 @lilypond[quote,verbatim,ragged-right]
3020 dolce = \markup { \italic \bold dolce }
3022 padText = { \once \override TextScript.padding = #5.0 }
3024 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
3027 violin = \relative {
3029 c''4._\dolce b8 a8 g a b |
3031 c4.^"hi there!" d8 e' f g d |
3032 c,4.\fthenp b8 c4 c-. |
3040 \layout { ragged-right = ##t }
3044 These variables are obviously useful for saving
3045 typing. But they're worth considering even if you
3046 only use them once -- they reduce complexity. Let's
3047 look at the previous example without any
3048 variables. It's a lot harder to read, especially
3052 violin = \relative @{
3054 c''4._\markup @{ \italic \bold dolce @} b8 a8 g a b |
3055 \once \override TextScript.padding = #5.0
3056 c4.^"hi there!" d8 e' f g d |
3058 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p
3065 @c TODO Replace the following with a better example -td
3066 @c Skylining handles this correctly without padText
3068 So far we've seen static substitution -- when LilyPond
3069 sees @code{\padText}, it replaces it with the stuff that
3070 we've defined it to be (ie the stuff to the right of
3073 LilyPond can handle non-static substitution, too (you
3074 can think of these as functions).
3076 @lilypond[quote,verbatim,ragged-right]
3078 #(define-music-function
3082 \once \override TextScript.padding = #padding
3086 c'''4^"piu mosso" b a b |
3088 c4^"piu mosso" d e f |
3090 c4^"piu mosso" fis a g |
3094 Using variables is also a good way to reduce work if the
3095 LilyPond input syntax changes (see
3096 @rprogram{Updating files with convert-ly}). If
3097 you have a single definition (such as @code{\dolce}) for all your
3098 input files (see @ref{Style sheets}), then if the syntax changes, you
3099 only need to update your single @code{\dolce} definition,
3100 instead of making changes throughout every @file{.ly} file.
3103 @node Scores and parts
3104 @subsection Scores and parts
3106 In orchestral music, all notes are printed twice. Once in a part for
3107 the musicians, and once in a full score for the conductor. Variables can
3108 be used to avoid double work. The music is entered once, and stored in
3109 a variable. The contents of that variable is then used to generate
3110 both the part and the full score.
3112 It is convenient to define the notes in a special file. For example,
3113 suppose that the file @file{horn-music.ly} contains the following part
3114 of a horn/@/bassoon duo
3117 hornNotes = \relative @{
3119 r4 f8 a | cis4 f | e4 d |
3124 Then, an individual part is made by putting the following in a file
3127 \include "horn-music.ly"
3130 instrument = "Horn in F"
3134 \transpose f c' \hornNotes
3141 \include "horn-music.ly"
3145 substitutes the contents of @file{horn-music.ly} at this position in
3146 the file, so @code{hornNotes} is defined afterwards. The command
3147 @code{\transpose f@tie{}c'} indicates that the argument, being
3148 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
3149 @code{f} is denoted by notated @code{c'}, which corresponds with the
3150 tuning of a normal French Horn in@tie{}F. The transposition can be seen
3151 in the following output
3153 @lilypond[quote,ragged-right]
3154 \transpose f c' \relative {
3156 r4 f8 a | cis4 f | e4 d |
3160 In ensemble pieces, one of the voices often does not play for many
3161 measures. This is denoted by a special rest, the multi-measure
3162 rest. It is entered with a capital @code{R} followed by a duration
3163 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
3164 etc.). By multiplying the
3165 duration, longer rests can be constructed. For example, this rest
3166 takes 3@tie{}measures in 2/4 time
3172 When printing the part, multi-rests
3173 must be condensed. This is done by setting a run-time variable
3176 \set Score.skipBars = ##t
3180 This command sets the property @code{skipBars} in the
3181 @code{Score} context to true (@code{##t}). Prepending the rest and
3182 this option to the music above, leads to the following result
3184 @lilypond[quote,ragged-right]
3185 \transpose f c' \relative {
3187 \set Score.skipBars = ##t
3189 r4 f8 a | cis4 f | e4 d |
3194 The score is made by combining all of the music together. Assuming
3195 that the other voice is in @code{bassoonNotes} in the file
3196 @file{bassoon-music.ly}, a score is made with
3199 \include "bassoon-music.ly"
3200 \include "horn-music.ly"
3203 \new Staff \hornNotes
3204 \new Staff \bassoonNotes
3211 @lilypond[quote,ragged-right]
3217 r4 f8 a | cis4 f | e4 d |
3222 r4 d,8 f | gis4 c | b4 bes |
3223 a8 e f4 | g4 d | gis4 f |