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
184 Merk op dat deze drie commando's -- @code{\header},
185 @code{\layout} en @code{\midi} -- speciaal zijn: in
186 tegenstelling tot veel andere commando's die met een
187 backslash (@code{\}) beginnen zijn het @emph{geen}
188 muziekuitdrukkingen en ze zijn ook geen onderdeel van een
189 muziekuitdrukking. Ze kunnen zowel binnen als buiten het
190 @code{\score}-blok worden geplaatst. Deze commando's worden
191 gewoonlijk dan ook buiten het @code{\score}-blok gezet
192 -- bijvoorbeeld, @code{\header} staat meestal boven het
193 @code{\score}-commando, zoals het in eerste voorbeeld van
196 De twee andere commando's die je niet eerder hebt gezien
197 zijn @code{\layout @{ @}} en @code{\midi @{@}}. Als deze
198 gebruikt worden als hierboven laten ze LilyPond
199 respectievelijk geprinte- en MIDI-uitvoer genereren. Een
200 volledige beschrijving van deze commando's is te vinden in
201 de Notatiehandleiding -- @ruser{Score layout}, en
202 @ruser{Creating MIDI files}.
204 @cindex partituren, verscheidene
205 @cindex boek blok, impliciet
206 @cindex impliciet boek blok
210 Je kunt meer dan een @code{\score}-blok gebruiken. Elk
211 wordt behandeld als een afzonderlijke partituur en ze worden
212 allemaal samengevoegd in een enkel uitvoerbestand. Een
213 @code{\book}-commando is niet nodig -- die wordt impliciet
214 aangemaakt. Echter, als je afzonderlijke uitvoerbestanden
215 vanuit een @file{.ly}-bestand wil maken, dan moet het
216 @code{\book}-commando worden gebruikt om de verschillende
217 secties aan te geven: elk @code{\book}-blok produceert
218 een apart uitvoerbestand.
222 Elk @code{\book}-blok geeft een apart uitvoerbestand (bijv.,
223 een PDF-bestand). Als je er geen expliciet toevoegt, stopt
224 LilyPond je gehele invoercode impliciet in een
227 Elk @code{\score}-blok is een apart brok muziek binnen een
230 @cindex opmaakblok, effect van locatie
232 Elk @code{\layout}-blok beïnvloedt het @code{\score}- of
233 @code{\book}-blok waarin het voorkomt -- d.w.z., een
234 @code{\layout}-blok binnen een @code{\score}-blok heeft
235 uitsluitend invloed op dat @code{\score}-blok, maar een
236 @code{\layout}-blok buiten een @code{\score}-blok (en dus
237 binnen een @code{\book}-blok, expliciet danwel impliciet)
238 beïnvloedt elke @code{\score} in dat @code{\book}.
240 Voor details zie @ruser{Multiple scores in a book}.
244 Een andere manier van afkorten is het gebruik van
245 variabelen, zoals getoond in @ref{Stukken organiseren met
246 variabelen}. Alle sjablonen gebruiken dat:
249 melodie = \relative @{
258 Als LilyPond naar dit bestand kijkt, neemt het de waarde van
259 @code{melodie} (alles na het isgelijkteken) en voegt die in
260 zodra ergens @code{\melody} staat. De naam van de variable
261 heeft verder geen speciale betekenis -- het kan net zo goed
262 @code{melodie}, @code{globaal}, @code{TijdSleutel},
263 @code{pianorechterhand}, of iets anders zijn. Bedenk dat je
264 vrijwel elke naam kunt gebruiken die je wilt, zolang die
265 maar bestaat uit letters en het niet de naam is van een
266 LilyPond-commando. Voor meer details, zie @ref{Saving
267 typing with variables and functions}. De precieze
268 beperkingen van variabelenamen staan beschreven in
269 @ruser{File structure}.
273 Voor een volledige definitie van het invoerformaat, zie
274 @ruser{File structure}.
277 @node Score is a (single) compound musical expression
278 @subsection Score is a (single) compound musical expression
283 @cindex contents of a score block
284 @cindex score block, contents of
285 @cindex compound music expression
286 @cindex music expression, compound
288 We saw the general organization of LilyPond input files in the
289 previous section, @ref{Introduction to the LilyPond file structure}.
290 But we seemed to skip over the most important part: how do we figure
291 out what to write after @code{\score}?
293 We didn't skip over it at all. The big mystery is simply that
294 there @emph{is} no mystery. This line explains it all:
297 @emph{A @code{\score} block must begin with a compound music expression.}
301 To understand what is meant by a music expression and a compound
302 music expression, you may find it useful to review the tutorial,
303 @ref{Music expressions explained}. In that section, we saw how to
304 build big music expressions from small pieces -- we started from
305 notes, then chords, etc. Now we're going to start from a big
306 music expression and work our way down. For simplicity, we'll use
307 just a singer and piano in our example. We don't need a
308 @code{StaffGroup} for this ensemble, which simply groups a number
309 of staves together with a bracket at the left, but we do need
310 staves for a singer and a piano, though.
315 \new Staff = "singer" <<
317 \new PianoStaff = "piano" <<
324 Here we have given names to the staves -- @qq{singer} and
325 @qq{piano}. This is not essential here, but it is a useful habit
326 to cultivate so that you can see at a glance what each stave is
329 Remember that we use @code{<< ... >>} instead of @code{@{ ... @}} to
330 show simultaneous music. This causes the vocal part and piano part
331 to appear one above the other in the score. The @code{<< ... >>}
332 construct would not be necessary for the Singer staff in the example
333 above if it were going to contain only one sequential music
334 expression, but @code{<< ... >>} rather than braces is necessary if
335 the music in the Staff is to contain two or more simultaneous
336 expressions, e.g. two simultaneous Voices, or a Voice with lyrics.
337 We're going to have a voice with lyrics, so angle brackets are
338 required. We'll add some real music later; for now let's just put
339 in some dummy notes and lyrics. If you've forgotten how to add lyrics
340 you may wish to review @code{\addlyrics} in @ref{Setting simple songs}.
342 @lilypond[verbatim,quote,ragged-right]
345 \new Staff = "singer" <<
346 \new Voice = "vocal" { c'1 }
349 \new PianoStaff = "piano" <<
350 \new Staff = "upper" { c'1 }
351 \new Staff = "lower" { c'1 }
358 Now we have a lot more details. We have the singer's staff: it
359 contains a @code{Voice} (in LilyPond, this term refers to a set of
360 notes, not necessarily vocal notes -- for example, a violin
361 generally plays one voice) and some lyrics. We also have a piano
362 staff: it contains an upper staff (right hand) and a lower staff
363 (left hand), although the lower staff has yet to be given a bass
366 At this stage, we could start filling in notes. Inside the curly
367 braces next to @code{\new Voice = "vocal"}, we could start writing
371 r4 d''8\noBeam g, c4 r
375 But if we did that, the @code{\score} section would get pretty
376 long, and it would be harder to understand what was happening. So
377 let's use variables instead. These were introduced at the end
378 of the previous section, remember? To ensure the contents of the
379 @code{text} variable are interpreted as lyrics we preface them with
380 @code{\lyricmode}. Like @code{\addlyrics}, this switches the input
381 mode to lyrics. Without that, LilyPond would try to interpret the
382 contents as notes, which would generate errors. (Several other
383 input modes are available, see @ruser{Input modes}.)
385 So, adding a few notes and a bass clef for the left hand, we now
386 have a piece of real music:
388 @lilypond[verbatim,quote,ragged-right]
389 melody = \relative { r4 d''8\noBeam g, c4 r }
390 text = \lyricmode { And God said, }
391 upper = \relative { <g' d g,>2~ <g d g,> }
392 lower = \relative { b,2 e }
396 \new Staff = "singer" <<
397 \new Voice = "vocal" { \melody }
400 \new PianoStaff = "piano" <<
401 \new Staff = "upper" { \upper }
402 \new Staff = "lower" {
412 When writing (or reading) a @code{\score} section, just take it
413 slowly and carefully. Start with the outer level, then work on
414 each smaller level. It also really helps to be strict with
415 indentation -- make sure that each item on the same level starts
416 on the same horizontal position in your text editor.
420 Notation Reference: @ruser{Structure of a score}.
423 @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
495 @subsection On the un-nestedness of brackets and ties
497 @cindex brackets, nesting
498 @cindex bracket types
499 @cindex brackets, enclosing vs. marking
501 You have already met a number of different types of bracket and
502 bracket-like constructs in writing the input file to LilyPond.
503 These obey different rules which can be confusing at first.
504 Let's first review the different types of brackets and bracket-like
507 @c attempt to force this onto a new page
509 @multitable @columnfractions .3 .7
510 @headitem Bracket Type
512 @item @code{@{ .. @}}
513 @tab Encloses a sequential segment of music
515 @tab Encloses the notes of a chord
516 @item @code{<< .. >>}
517 @tab Encloses simultaneous music expressions
519 @tab Marks the start and end of a slur
520 @item @code{\( .. \)}
521 @tab Marks the start and end of a phrasing slur
523 @tab Marks the start and end of a manual beam
526 To these we should add other constructs which generate lines
527 between or across notes: ties (marked by a tilde, @code{~}),
528 tuplets written as @code{\times x/y @{..@}}, and grace notes
529 written as @code{\grace@{..@}}.
531 Outside LilyPond, the conventional use of brackets requires the
532 different types to be properly nested, like this, @code{<< [ @{ ( .. )
533 @} ] >>}, with the closing brackets being encountered in exactly the
534 opposite order to the opening brackets. This @strong{is} a
535 requirement for the three types of bracket described by the word
536 @q{Encloses} in the table above -- they must nest properly. However,
537 the remaining bracket-like constructs, described with the word
538 @q{Marks} in the table above together with ties and tuplets, do
539 @strong{not} have to nest properly with any of the brackets or
540 bracket-like constructs. In fact, these are not brackets in
541 the sense that they enclose something -- they are simply markers to
542 indicate where something starts and ends.
544 So, for example, a phrasing slur can start before a manually
545 inserted beam and end before the end of the beam -- not very
546 musical, perhaps, but possible:
548 @lilypond[quote,verbatim,ragged-right]
549 \relative { g'8\( a b[ c b\) a] g4 }
552 In general, different kinds of brackets, bracket-like constructs,
553 and those implied by tuplets, ties and grace notes, may be mixed
554 freely. This example shows a beam extending into a tuplet (line 1),
555 a slur extending into a tuplet (line 2), a beam and a slur
556 extending into a tuplet, a tie crossing two tuplets, and a
557 phrasing slur extending out of a tuplet (lines 3 and 4).
559 @lilypond[quote,verbatim,ragged-right]
561 r16[ g' \tuplet 3/2 { r16 e'8] }
562 g,16( a \tuplet 3/2 { b16 d) e }
563 g,8[( a \tuplet 3/2 { b8 d) e~] } |
564 \tuplet 5/4 { e32\( a, b d e } a4.\)
569 @node Voices contain music
570 @section Voices contain music
572 Singers need voices to sing, and so does LilyPond.
573 The actual music for all instruments in a score
574 is contained in Voices -- the most fundamental
575 of all LilyPond's concepts.
578 * I'm hearing Voices::
579 * Explicitly instantiating voices::
580 * Voices and vocals::
583 @node I'm hearing Voices
584 @subsection I'm hearing Voices
588 @cindex multiple voices
589 @cindex voices, multiple
590 @cindex Voice context
591 @cindex context, Voice
592 @cindex simultaneous music
593 @cindex music, simultaneous
594 @cindex concurrent music
595 @cindex music, concurrent
596 @cindex voices vs. chords
597 @cindex chords vs. voices
599 The lowest, most fundamental or innermost layers in a LilyPond
600 score are called @q{Voice contexts} or just @q{Voices} for short.
601 Voices are sometimes called @q{layers} in other notation
604 In fact, a Voice layer or context is the only one which can contain
605 music. If a Voice context is not explicitly declared one is created
606 automatically, as we saw at the beginning of this chapter. Some
607 instruments such as an Oboe can play only one note at a time. Music
608 written for such instruments requires just a single voice. Instruments
609 which can play more than one note at a time like the piano will often
610 require multiple voices to encode the different concurrent notes and
611 rhythms they are capable of playing.
613 A single voice can contain many notes in a chord, of course,
614 so when exactly are multiple voices needed? Look first at
615 this example of four chords:
617 @lilypond[quote,verbatim,ragged-right]
620 <d' g>4 <d fis> <d a'> <d g>
624 This can be expressed using just the single angle bracket chord
625 symbols, @code{< ... >}, and for this just a single voice is
626 needed. But suppose the F-sharp were actually an eighth-note
627 followed by an eighth-note G, a passing note on the way to the A?
628 Now we have two notes which start at the same time but have
629 different durations: the quarter-note D and the eighth-note
630 F-sharp. How are these to be coded? They cannot be written as
631 a chord because all the notes in a chord must have the same
632 duration. And they cannot be written as two sequential notes
633 as they need to start at the same time. This is when two
636 Let us see how this is done in LilyPond input syntax.
641 The easiest way to enter fragments with more than one voice on a
642 staff is to enter each voice as a sequence (with @code{@{...@}}),
643 and combine them simultaneously with angle brackets, @code{<<...>>}.
644 The fragments must also be separated with double backward slashes,
645 @code{\\}, to place them in separate voices. Without these, the
646 notes would be entered into a single voice, which would usually
647 cause errors. This technique is particularly suited to pieces of
648 music which are largely homophonic with occasional short sections
651 Here's how we split the chords above into two voices and add both
652 the passing note and a slur:
654 @lilypond[quote,verbatim,ragged-right]
657 % Voice = "1" Voice = "2"
658 << { g'4 fis8( g) a4 g } \\ { d4 d d d } >>
662 Notice how the stems of the second voice now point down.
664 Here's another simple example:
666 @lilypond[quote,verbatim,ragged-right]
669 % Voice = "1" Voice = "2"
670 << { r4 g' g4. a8 } \\ { d,2 d4 g } >> |
671 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
672 << { a2. r4 } \\ { fis2. s4 } >> |
676 It is not necessary to use a separate @code{<< \\ >>} construct
677 for each bar. For music with few notes in each bar this layout
678 can help the legibility of the code, but if there are many
679 notes in each bar it may be better to split out each voice
680 separately, like this:
682 @lilypond[quote,verbatim,ragged-right]
685 \relative { % Voice = "1"
690 \relative { % Voice = "2"
699 @cindex voices, naming
700 @cindex voices crossing brackets
701 @cindex slurs crossing brackets
702 @cindex ties crossing brackets
704 This example has just two voices, but the same construct may be
705 used to encode three or more voices by adding more back-slash
708 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
709 The first contexts set the @emph{outer} voices, the highest
710 voice in context @code{"1"} and the lowest voice in context
711 @code{"2"}. The inner voices go in contexts @code{"3"} and
712 @code{"4"}. In each of these contexts, the vertical direction
713 of slurs, stems, ties, dynamics etc., is set appropriately.
715 @lilypond[quote,verbatim]
716 \new Staff \relative {
719 % Voice = "1" Voice = "2" Voice = "3"
720 << { g4 f e } \\ { r8 e4 d c8~ } >> |
721 << { d2 e } \\ { c8 b16 a b8 g~ 2 } \\ { s4 b c2 } >> |
725 These voices are all separate from the main voice that contains
726 the notes just outside the @code{<< .. >>} construct. Let's call
727 this the @emph{simultaneous construct}. Slurs and ties may only
728 connect notes within the same voice, so slurs and ties cannot go
729 into or out of a simultaneous construct. Conversely,
730 parallel voices from separate simultaneous constructs on the same
731 staff are the same voice. Other voice-related properties also
732 carry across simultaneous constructs. Here is the same example,
733 with different colors and note heads for each voice. Note that
734 changes in one voice do not affect other voices, but they do
735 persist in the same voice later. Note also that tied notes may be
736 split across the same voices in two constructs, shown here in the
739 @lilypond[quote,verbatim]
740 \new Staff \relative {
769 @funindex \voiceOneStyle
770 @funindex \voiceTwoStyle
771 @funindex \voiceThreeStyle
772 @funindex \voiceFourStyle
773 @funindex \voiceNeutralStyle
775 The commands @code{\voiceXXXStyle} are mainly intended for use in
776 educational documents such as this one. They modify the color
777 of the note head, the stem and the beams, and the style of the
778 note head, so that the voices may be easily distinguished.
779 Voice one is set to red diamonds, voice two to blue triangles,
780 voice three to green crossed circles, and voice four (not used
781 here) to magenta crosses; @code{\voiceNeutralStyle} (also not
782 used here) reverts the style back to the default.
783 We shall see later how commands like these may be created by the
785 See @ref{Visibility and color of objects} and
786 @ref{Using variables for tweaks}.
788 @cindex polyphony and relative note entry
789 @cindex relative note entry and polyphony
791 Polyphony does not change the relationship of notes within a
792 @code{\relative} block. Each note is still calculated relative to
793 the note immediately preceding it, or to the first note of the
794 preceding chord. So in
797 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
801 @code{noteB} is relative to @code{noteA} @*
802 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
803 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
805 @code{noteE} is relative to @code{noteD}, not @code{noteA}.
807 An alternative way, which may be clearer if the notes in the
808 voices are widely separated, is to place a @code{\relative}
809 command at the start of each voice:
812 \relative c' @{ noteA ... @}
814 \relative c'' @{ < noteB noteC > ... @}
816 \relative g' @{ noteD ... @}
818 \relative c' @{ noteE ... @}
821 Let us finally analyze the voices in a more complex piece of music.
822 Here are the notes from the first two bars of the second of Chopin's
823 Deux Nocturnes, Op 32. This example will be used at later stages in
824 this and the next chapter to illustrate several techniques for
825 producing notation, so please ignore for now anything in the
826 underlying code which looks mysterious and concentrate just on the
827 music and the voices -- the complications will all be explained in
830 @c The following should appear as music without code
831 @lilypond[quote,ragged-right]
832 \new Staff \relative {
838 % Ignore these for now - they are explained in Ch 4
839 \once \override NoteColumn.ignore-collision = ##t
841 \once \override NoteColumn.force-hshift = #0.5
847 \override NoteColumn.force-hshift = #0
855 The direction of the stems is often used to indicate the continuity of
856 two simultaneous melodic lines. Here the stems of the highest notes
857 are all pointing up and the stems of the lower notes are all pointing
858 down. This is the first indication that more than one voice is
861 But the real need for multiple voices arises when notes
862 which start at the same time have different durations.
863 Look at the notes which start at beat three in the first
864 bar. The A-flat is a dotted quarter note, the F is a
865 quarter note and the D-flat is a half note. These
866 cannot be written as a chord as all the notes in a chord
867 must have the same duration. Neither can they be written
868 as sequential notes, as they must start at the same time.
869 This section of the bar requires three voices, and the
870 normal practice would be to write the whole bar as three
871 voices, as shown below, where we have used different note heads
872 and colors for the three voices. Again, the code behind this
873 example will be explained later, so ignore anything you do
876 @c The following should appear as music without code
877 @c The three voice styles should be defined in -init
878 @lilypond[quote,ragged-right]
879 \new Staff \relative {
888 % Ignore these for now - they are explained in Ch 4
889 \once \override NoteColumn.ignore-collision = ##t
891 \once \override NoteColumn.force-hshift = #0.5
894 \\ % No Voice three (we want stems down)
897 \override NoteColumn.force-hshift = #0
906 Let us try to encode this music from scratch. As we
907 shall see, this encounters some difficulties. We begin as
908 we have learnt, using the @code{<< \\ >>} construct to
909 enter the music of the first bar in three voices:
911 @lilypond[quote,verbatim,ragged-right]
912 \new Staff \relative {
915 { c''2 aes4. bes8 } \\ { <ees, c>2 des } \\ { aes'2 f4 fes }
922 @cindex voices and stem directions
923 @cindex stem directions and voices
926 The stem directions are automatically assigned with the
927 odd-numbered voices taking upward stems and the even-numbered
928 voices downward ones. The stems for voices 1 and 2 are right,
929 but the stems in voice 3 should go down in this particular piece
930 of music. We can correct this by skipping voice three
931 and placing the music in voice four. This is done by simply
932 adding another pair of @code{\\}.
934 @lilypond[quote,verbatim,ragged-right]
935 \new Staff \relative {
941 \\ % Omit Voice three
950 We see that this fixes the stem direction, but the horizontal
951 placement of notes is not what we want. LilyPond shifts the
952 inner notes when they or their stems would collide with outer
953 voices, but this is not appropriate for piano music. In other
954 situations, the shifts LilyPond applies might fail to clear
955 the collisions. LilyPond provides several ways to adjust the
956 horizontal placing of notes. We are not quite ready yet to see
957 how to correct this, so we shall leave this problem until a
958 later section --- see the @code{force-hshift} property in
959 @ref{Fixing overlapping notation}.
961 @warning{Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be
962 created @q{across} voices.}
966 Notation Reference: @ruser{Multiple voices}.
969 @node Explicitly instantiating voices
970 @subsection Explicitly instantiating voices
976 @funindex \voiceThree
983 @cindex voice contexts, creating
985 Voice contexts can also be created manually
986 inside a @code{<< >>} block to create polyphonic music, using
987 @code{\voiceOne} @dots{} @code{\voiceFour} to indicate the required
988 directions of stems, slurs, etc. In longer scores this method
989 is clearer, as it permits the voices to be separated and to be
990 given more descriptive names.
992 Specifically, the construct @code{<< \\ >>} which we used in
993 the previous section:
998 << @{ e'4 f g a @} \\ @{ c,4 d e f @} >>
1008 \new Voice = "1" @{ \voiceOne \relative @{ e'4 f g a @} @}
1009 \new Voice = "2" @{ \voiceTwo \relative @{ c'4 d e f @} @}
1013 Both of the above would produce
1015 @c The following example should not display the code
1016 @lilypond[ragged-right,quote]
1018 \new Voice = "1" { \voiceOne \relative { e'4 f g a } }
1019 \new Voice = "2" { \voiceTwo \relative { c'4 d e f } }
1023 @cindex voices, reverting to single
1024 @cindex reverting to a single voice
1026 The @code{\voiceXXX} commands set the direction of stems, slurs,
1027 ties, articulations, text annotations, augmentation dots of dotted
1028 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
1029 make these objects point upwards, while @code{\voiceTwo} and
1030 @code{\voiceFour} make them point downwards. These commands also
1031 generate a horizontal shift for each voice when this is required
1032 to avoid clashes of note heads. The command @code{\oneVoice}
1033 reverts the settings back to the normal values for a single voice.
1035 Let us see in some simple examples exactly what effect
1036 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
1037 markup, ties, slurs, and dynamics:
1039 @lilypond[quote,ragged-right,verbatim]
1041 % Default behavior or behavior after \oneVoice
1042 c'4 d8~ 8 e4( f | g4 a) b-> c |
1046 @lilypond[quote,ragged-right,verbatim]
1049 c'4 d8~ 8 e4( f | g4 a) b-> c |
1051 c,4 d8~ 8 e4( f | g4 a) b-> c |
1055 @lilypond[quote,ragged-right,verbatim]
1058 c'4 d8~ 8 e4( f | g4 a) b-> c |
1060 c,4 d8~ 8 e4( f | g4 a) b-> c |
1064 Now let's look at three different ways to notate the same passage of
1065 polyphonic music, each of which is advantageous in different
1066 circumstances, using the example from the previous section.
1068 An expression that appears directly inside a @code{<< >>} belongs to the
1069 main voice (but, note, @strong{not} in a @code{<< \\ >>} construct).
1070 This is useful when extra voices appear while the main voice is playing.
1071 Here is a more correct rendition of our example. The red diamond-shaped
1072 notes demonstrate that the main melody is now in a single voice context,
1073 permitting a phrasing slur to be drawn over them.
1075 @lilypond[quote,ragged-right,verbatim]
1076 \new Staff \relative {
1078 % This section is homophonic
1080 % Start simultaneous section of three voices
1082 % Continue the main voice in parallel
1083 { g4 f e | d2 e) | }
1084 % Initiate second voice
1086 % Set stems, etc., down
1088 r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
1090 % Initiate third voice
1092 % Set stems, etc, up
1100 @cindex nesting music expressions
1101 @cindex nesting simultaneous constructs
1102 @cindex nesting voices
1103 @cindex voices, temporary
1104 @cindex voices, nesting
1106 More deeply nested polyphony constructs are possible, and if a
1107 voice appears only briefly this might be a more natural way to
1110 @lilypond[quote,ragged-right,verbatim]
1111 \new Staff \relative {
1114 { g4 f e | d2 e) | }
1119 { c8 b16 a b8 g~ 2 | }
1130 @cindex spacing notes
1132 This method of nesting new voices briefly is useful
1133 when only small sections of the music
1134 are polyphonic, but when the whole staff is largely polyphonic
1135 it can be clearer to use multiple voices throughout, using
1136 spacing notes to step over sections where the voice is silent,
1139 @lilypond[quote,ragged-right,verbatim]
1140 \new Staff \relative <<
1141 % Initiate first voice
1144 c'16^( d e f g4 f e | d2 e) |
1146 % Initiate second voice
1148 % Set stems, etc, down
1150 s4 r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
1152 % Initiate third voice
1154 % Set stems, etc, up
1161 @subsubheading Note columns
1164 @cindex note collisions
1165 @cindex collisions, notes
1166 @cindex shift commands
1173 @funindex \shiftOnnn
1176 Closely spaced notes in a chord, or notes occurring at the same
1177 time in different voices, are arranged in two, occasionally more,
1178 columns to prevent the note heads overlapping. These are called
1179 note columns. There are separate columns for each voice, and
1180 the currently specified voice-dependent shift is applied to the
1181 note column if there would otherwise be a collision. This can
1182 be seen in the example above. In bar 2 the C in voice two is
1183 shifted to the right relative to the D in voice one, and in the
1184 final chord the C in voice three is also shifted to the right
1185 relative to the other notes.
1187 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1188 @code{\shiftOff} commands specify the degree to which notes and
1189 chords of the voice should be shifted if a collision
1190 would otherwise occur. By default, the outer voices (normally
1191 voices one and two) have @code{\shiftOff} specified, while the
1192 inner voices (three and four) have @code{\shiftOn} specified.
1193 When a shift is applied, voices one and three are shifted to
1194 the right and voices two and four to the left.
1196 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1197 levels which may be specified temporarily to resolve collisions
1198 in complex situations -- see @ref{Real music example}.
1200 A note column can contain just one note (or chord) from a voice
1201 with stems up and one note (or chord) from a voice with stems
1202 down. If notes from two voices which have their stems in the
1203 same direction are placed at the same position and both voices
1204 have no shift or the same shift specified, the error message
1205 @qq{Too many clashing note columns} will be produced.
1209 Notation Reference: @ruser{Multiple voices}.
1212 @node Voices and vocals
1213 @subsection Voices and vocals
1215 Vocal music presents a special difficulty: we need to combine two
1216 expressions -- notes and lyrics.
1218 @funindex \new Lyrics
1222 @cindex Lyrics context, creating
1223 @cindex lyrics, linking to voice
1225 You have already seen the @code{\addlyrics@{@}} command, which
1226 handles simple scores well. However, this technique is
1227 quite limited. For more complex music, you must introduce the
1228 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1230 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1231 name assigned to the Voice.
1233 @lilypond[quote,verbatim]
1235 \new Voice = "one" {
1239 c''4 b8. a16 | g4. f8 | e4 d | c2 |
1242 \new Lyrics \lyricsto "one" {
1243 No more let | sins and | sor -- rows | grow. |
1248 Note that the lyrics must be linked to a @code{Voice} context,
1249 @emph{not} a @code{Staff} context. This is a case where it is
1250 necessary to create @code{Staff} and @code{Voice} contexts
1253 @cindex lyrics and beaming
1254 @cindex beaming and lyrics
1255 @funindex \autoBeamOff
1256 @funindex autoBeamOff
1258 The automatic beaming which LilyPond uses by default works well
1259 for instrumental music, but not so well for music with lyrics,
1260 where beaming is either not required at all or is used to indicate
1261 melismata in the lyrics. In the example above we use the command
1262 @code{\autoBeamOff} to turn off the automatic beaming.
1264 @funindex \new ChoirStaff
1265 @funindex ChoirStaff
1266 @funindex \lyricmode
1268 @cindex vocal score structure
1271 Let us reuse the earlier example from Judas Maccabæus to
1272 illustrate this more flexible technique. We first recast
1273 it to use variables so the music and lyrics can be separated
1274 from the staff structure. We also introduce a ChoirStaff
1275 bracket. The lyrics themselves must be introduced with
1276 @code{\lyricmode} to ensure they are interpreted as lyrics
1279 @lilypond[quote,verbatim]
1280 global = { \key f \major \time 6/8 \partial 8 }
1282 SopOneMusic = \relative {
1283 c''8 | c8([ bes)] a a([ g)] f | f'4. b, | c4.~ 4
1285 SopOneLyrics = \lyricmode {
1286 Let | flee -- cy flocks the | hills a -- dorn, __
1288 SopTwoMusic = \relative {
1289 r8 | r4. r4 c'8 | a'8([ g)] f f([ e)] d | e8([ d)] c bes'
1291 SopTwoLyrics = \lyricmode {
1292 Let | flee -- cy flocks the | hills a -- dorn,
1298 \new Voice = "SopOne" {
1302 \new Lyrics \lyricsto "SopOne" {
1307 \new Voice = "SopTwo" {
1311 \new Lyrics \lyricsto "SopTwo" {
1319 This is the basic structure of all vocal scores. More staves may be
1320 added as required, more voices may be added to the staves, more verses
1321 may be added to the lyrics, and the variables containing the music can
1322 easily be placed in separate files should they become too long.
1324 @cindex hymn structure
1325 @cindex SATB structure
1326 @cindex vocal scores with multiple verses
1327 @cindex multiple vocal verses
1328 @cindex verses, multiple vocal
1330 Here is an example of the first line of a hymn with four
1331 verses, set for SATB. In this case the words for all four
1332 parts are the same. Note how we use variables to separate the
1333 music notation and words from the staff structure. See too
1334 how a variable, which we have chosen to call @q{keyTime}, is used
1335 to hold several commands for use within the two staves. In other
1336 examples this is often called @q{global}.
1338 @lilypond[quote,verbatim]
1339 keyTime = { \key c \major \time 4/4 \partial 4 }
1341 SopMusic = \relative { c'4 | e4. e8 g4 g | a4 a g }
1342 AltoMusic = \relative { c'4 | c4. c8 e4 e | f4 f e }
1343 TenorMusic = \relative { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1344 BassMusic = \relative { c4 | c4. c8 c4 c | f8 g a b c4 }
1347 \lyricmode { E -- | ter -- nal fa -- ther, | strong to save, }
1349 \lyricmode { O | Christ, whose voice the | wa -- ters heard, }
1351 \lyricmode { O | Ho -- ly Spi -- rit, | who didst brood }
1353 \lyricmode { O | Tri -- ni -- ty of | love and pow'r }
1359 \new Voice = "Sop" { \voiceOne \keyTime \SopMusic }
1360 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1361 \new Lyrics \lyricsto "Sop" { \VerseOne }
1362 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1363 \new Lyrics \lyricsto "Sop" { \VerseThree }
1364 \new Lyrics \lyricsto "Sop" { \VerseFour }
1368 \new Voice = "Tenor" { \voiceOne \keyTime \TenorMusic }
1369 \new Voice = "Bass" { \voiceTwo \BassMusic }
1377 Notation Reference: @ruser{Vocal music}.
1380 @node Contexts and engravers
1381 @section Contexts and engravers
1383 Contexts and engravers have been mentioned informally
1384 in earlier sections; we now must look at
1385 these concepts in more detail, as they are important
1386 in the fine-tuning of LilyPond output.
1390 * Contexts explained::
1391 * Creating contexts::
1392 * Engravers explained::
1393 * Modifying context properties::
1394 * Adding and removing engravers::
1397 @node Contexts explained
1398 @subsection Contexts explained
1400 @cindex contexts explained
1402 When music is printed, many notational elements which do not
1403 appear explicitly in the input file must be added to the
1404 output. For example, compare the input and output of the
1407 @lilypond[quote,verbatim]
1408 \relative { cis''4 cis2. | a4 a2. | }
1411 The input is rather sparse, but in the output, bar lines,
1412 accidentals, clef, and time signature have been added. When
1413 LilyPond @emph{interprets} the input the musical information
1414 is parsed from left to right, similar to the way a performer
1415 reads the score. While reading the input, the program remembers
1416 where measure boundaries are, and which pitches require explicit
1417 accidentals. This information must be held on several levels.
1418 For example, an accidental affects only a single staff, while
1419 a bar line must be synchronized across the entire score.
1421 Within LilyPond, these rules and bits of information are grouped in
1422 @emph{Contexts}. We have already introduced the @code{Voice} context.
1423 Others are the @code{Staff} and @code{Score} contexts. Contexts are
1424 hierarchical to reflect the hierarchical nature of a musical score.
1425 For example: a @code{Staff} context can contain many @code{Voice}
1426 contexts, and a @code{Score} context can contain many @code{Staff}
1430 @sourceimage{context-example,5cm,,}
1433 Each context has the responsibility for enforcing some notation rules,
1434 creating some notation objects and maintaining the associated
1435 properties. For example, the @code{Voice} context may introduce an
1436 accidental and then the @code{Staff} context maintains the rule to
1437 show or suppress the accidental for the remainder of the measure.
1439 As another example, the synchronization of bar lines is, by default,
1440 handled in the @code{Score} context.
1441 However, in some music we may not want the bar lines to be
1442 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1443 In such cases, we must modify the default settings of the
1444 @code{Score} and @code{Staff} contexts.
1446 For very simple scores, contexts are created implicitly, and you need
1447 not be aware of them. For larger pieces, such as anything with more
1448 than one staff, they must be
1449 created explicitly to make sure that you get as many staves as you
1450 need, and that they are in the correct order. For typesetting pieces
1451 with specialized notation, it is usual to modify existing, or
1452 even to define totally new, contexts.
1454 In addition to the @code{Score,} @code{Staff} and
1455 @code{Voice} contexts there are contexts which fit between
1456 the score and staff levels to control staff groups, such as the
1457 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1458 are also alternative staff and voice contexts, and contexts for
1459 lyrics, percussion, fret boards, figured bass, etc.
1461 The names of all context types are formed from one or more
1462 words, each word being capitalized and joined immediately to the
1463 preceding word with no hyphen or underscore, e.g.,
1464 @code{GregorianTranscriptionStaff}.
1468 Notation Reference: @ruser{Contexts explained}.
1471 @node Creating contexts
1472 @subsection Creating contexts
1476 @cindex new contexts
1477 @cindex creating contexts
1478 @cindex contexts, creating
1480 In an input file a score block, introduced with a @code{\score}
1481 command, contains a single music expression and an associated
1482 output definition (either a @code{\layout} or a @code{\midi} block).
1483 The @code{Score} context is usually left to be created automatically
1484 when the interpretation of that music expression starts.
1486 For scores with only one voice and one staff, the @code{Voice} and
1487 @code{Staff} contexts may also be left to be created automatically,
1488 but for more complex scores it is necessary to create them by hand.
1489 The simplest command that does this is @code{\new}. It is prepended
1490 to a music expression, for example
1493 \new @var{type} @var{music-expression}
1497 where @var{type} is a context name (like @code{Staff} or
1498 @code{Voice}). This command creates a new context, and starts
1499 interpreting the @var{music-expression} within that context.
1501 @warning{@bs{}@code{new Score} should not be used as the essential
1502 top-level @code{Score} context is created automatically when the music
1503 expression within the @bs{}@code{score} block is interpreted. Score-wide
1504 default values of context properties can be changed within the
1505 @bs{}@code{layout} block. See @ref{Modifying context properties}}
1507 You have seen many practical examples which created new
1508 @code{Staff} and @code{Voice} contexts in earlier sections, but
1509 to remind you how these commands are used in practice, here's an
1510 annotated real-music example:
1512 @lilypond[quote,verbatim,ragged-right]
1513 \score { % start of single compound music expression
1514 << % start of simultaneous staves section
1516 \new Staff { % create RH staff
1519 \new Voice { % create voice for RH notes
1520 \relative { % start of RH notes
1526 \new Staff << % create LH staff; needs two simultaneous voices
1529 \new Voice { % create LH voice one
1531 \relative { % start of LH voice one notes
1532 g8 <bes d> ees, <g c> |
1533 g8 <bes d> ees, <g c> |
1534 } % end of LH voice one notes
1535 } % end of LH voice one
1536 \new Voice { % create LH voice two
1538 \relative { % start of LH voice two notes
1541 } % end of LH voice two notes
1542 } % end of LH voice two
1543 >> % end of LH staff
1544 >> % end of simultaneous staves section
1545 } % end of single compound music expression
1548 (Note how all the statements which open a block with either a
1549 curly bracket, @code{@{}, or double angle brackets, @code{<<},
1550 are indented by two further spaces, and the corresponding
1551 closing bracket is indented by exactly the same amount. While
1552 this is not required, following this practice will greatly
1553 reduce the number of @q{unmatched bracket} errors, and is
1554 strongly recommended. It enables the structure of the music to
1555 be seen at a glance, and any unmatched brackets will be obvious.
1556 Note too how the LH staff is created using double angle brackets
1557 because it requires two voices for its music, whereas the RH staff
1558 is created with a single music expression surrounded by curly
1559 brackets because it requires only one voice.)
1561 @cindex contexts, naming
1562 @cindex naming contexts
1564 The @code{\new} command may also give an identifying name to the
1565 context to distinguish it from other contexts of the same type,
1568 \new @var{type} = @var{id} @var{music-expression}
1571 Note the distinction between the name of the context type,
1572 @code{Staff}, @code{Voice}, etc, and the identifying name of a
1573 particular instance of that type, which can be any sequence of letters
1574 invented by the user. Digits and spaces can also be used in the
1575 identifying name, but then it has to be placed in quotes,
1576 i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
1577 The identifying name is used to
1578 refer back to that particular instance of a context. We saw this in
1579 use in the section on lyrics, see @ref{Voices and vocals}.
1583 Notation Reference: @ruser{Creating contexts}.
1586 @node Engravers explained
1587 @subsection Engravers explained
1591 Every mark on the printed output of a score produced by LilyPond
1592 is produced by an @code{Engraver}. Thus there is an engraver
1593 to print staves, one to print note heads, one for stems, one for
1594 beams, etc, etc. In total there are over 120 such engravers!
1595 Fortunately, for most scores it is not necessary to know about
1596 more than a few, and for simple scores you do not need to know
1599 Engravers live and operate in Contexts. Engravers such as the
1600 @code{Metronome_mark_engraver}, whose action and output apply to the
1601 score as a whole, operate in the highest level context -- the
1602 @code{Score} context.
1604 The @code{Clef_engraver} and @code{Key_engraver} are to be
1605 found in every @code{Staff} Context, as different staves may require
1606 different clefs and keys.
1608 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1609 in every @code{Voice} context, the lowest level context of all.
1611 Each engraver processes the particular objects associated
1612 with its function, and maintains the properties that relate
1613 to that function. These properties, like the properties
1614 associated with contexts, may be modified to change the
1615 operation of the engraver or the appearance of those elements
1616 in the printed score.
1618 Engravers all have compound names formed from words which
1619 describe their function. Just the first word is capitalized,
1620 and the remainder are joined to it with underscores. Thus
1621 the @code{Staff_symbol_engraver} is responsible for creating the
1622 lines of the staff, the @code{Clef_engraver} determines and sets
1623 the pitch reference point on the staff by drawing a clef symbol.
1625 Here are some of the most common engravers together with their
1626 function. You will see it is usually easy to guess the function
1627 from the name, or vice versa.
1629 @multitable @columnfractions .3 .7
1632 @item Accidental_engraver
1633 @tab Makes accidentals, cautionary and suggested accidentals
1638 @item Completion_heads_engraver
1639 @tab Splits notes which cross bar lines
1640 @item Dynamic_engraver
1641 @tab Creates hairpins and dynamic texts
1642 @item Forbid_line_break_engraver
1643 @tab Prevents line breaks if a musical element is still active
1645 @tab Creates the key signature
1646 @item Metronome_mark_engraver
1647 @tab Engraves metronome marking
1648 @item Note_heads_engraver
1649 @tab Engraves note heads
1652 @item Staff_symbol_engraver
1653 @tab Engraves the five (by default) lines of the staff
1655 @tab Creates stems and single-stem tremolos
1656 @item Time_signature_engraver
1657 @tab Creates time signatures
1662 We shall see later how the output of LilyPond can be changed
1663 by modifying the action of Engravers.
1667 Internals reference: @rinternals{Engravers and Performers}.
1670 @node Modifying context properties
1671 @subsection Modifying context properties
1673 @cindex context properties
1674 @cindex context properties, modifying
1675 @cindex modifying context properties
1681 Contexts are responsible for holding the values of a number of
1682 context @emph{properties}. Many of them can be changed to
1683 influence the interpretation of the input and so change the
1684 appearance of the output. They are changed by the
1685 @code{\set} command. This takes the form
1688 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1691 Where the @emph{ContextName} is usually @code{Score},
1692 @code{Staff} or @code{Voice}. It may be omitted,
1693 in which case the current context (typically @code{Voice}) is assumed.
1695 The names of context properties consist of words joined
1696 together with no hyphens or underscores, all except the
1697 first having a capital letter. Here are a few examples
1698 of some commonly used ones. There are many more.
1700 @c attempt to force this onto a new page
1702 @multitable @columnfractions .25 .15 .45 .15
1703 @headitem propertyName
1709 @tab If true, set extra natural signs before accidentals
1710 @tab @code{#t}, @code{#f}
1711 @item currentBarNumber
1713 @tab Set the current bar number
1717 @tab If true, print slurs both above and below notes
1718 @tab @code{#t}, @code{#f}
1719 @item instrumentName
1721 @tab Set the name to be placed at the start of the staff
1722 @tab @code{"Cello I"}
1725 @tab Increase or decrease the font size
1729 @tab Set the text to print before the start of a verse
1734 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1735 an Integer is a positive whole number, a Real is a positive
1736 or negative decimal number, and text is enclosed in double
1737 apostrophes. Note the occurrence of hash signs,
1738 (@code{#}), in two different places -- as part of the Boolean
1739 value before the @code{t} or @code{f}, and before @emph{value}
1740 in the @code{\set} statement. So when a Boolean is being
1741 entered you need to code two hash signs, e.g., @code{##t}.
1743 @cindex properties operating in contexts
1744 @cindex setting properties within contexts
1746 Before we can set any of these properties we need to know
1747 in which context they operate. Sometimes this is obvious,
1748 but occasionally it can be tricky. If the wrong context
1749 is specified, no error message is produced, but the expected
1750 action will not take place. For example, the
1751 @code{instrumentName} clearly lives in the @code{Staff} context, since
1752 it is the staff that is to be named.
1753 In this example the first staff is labeled, but not the second,
1754 because we omitted the context name.
1756 @lilypond[quote,verbatim,ragged-right]
1758 \new Staff \relative {
1759 \set Staff.instrumentName = #"Soprano"
1762 \new Staff \relative {
1763 \set instrumentName = #"Alto" % Wrong!
1769 Remember the default context name is @code{Voice}, so the second
1770 @code{\set} command set the property @code{instrumentName} in the
1771 @code{Voice} context to @qq{Alto}, but as LilyPond does not look
1772 for any such property in the @code{Voice} context, no
1773 further action took place. This is not an error, and no error
1774 message is logged in the log file.
1776 Similarly, if the property name is mis-spelt no error message is
1777 produced, and clearly the expected action cannot be performed. In
1778 fact, you can set any (fictitious) @q{property} using any name you
1779 like in any context that exists by using the @code{\set} command. But
1780 if the name is not known to LilyPond it will not cause any action to
1781 be taken. Some text editors with special support for LilyPond input
1782 files document property names with bullets when you hover them with
1783 the mouse, like JEdit with LilyPondTool, or highlight unknown property
1784 names differently, like ConTEXT. If you do not use an editor with
1785 such features, it is recommended to check the property name in the
1786 Internals Reference: see @rinternals{Tunable context properties}, or
1787 @rinternals{Contexts}.
1789 The @code{instrumentName} property will take effect only
1790 if it is set in the @code{Staff} context, but
1791 some properties can be set in more than one context.
1792 For example, the property @code{extraNatural} is by
1793 default set to ##t (true) for all staves.
1794 If it is set to ##f (false) in one particular @code{Staff}
1795 context it applies just to the accidentals on that staff.
1796 If it is set to false in the @code{Score} context
1797 it applies to all staves.
1799 So this turns off extra naturals in one staff:
1801 @lilypond[quote,verbatim,ragged-right]
1803 \new Staff \relative {
1806 \new Staff \relative {
1807 \set Staff.extraNatural = ##f
1814 and this turns them off in all staves:
1816 @lilypond[quote,verbatim,ragged-right]
1818 \new Staff \relative {
1821 \new Staff \relative {
1822 \set Score.extraNatural = ##f
1828 As another example, if @code{clefTransposition} is set in
1829 the @code{Score} context this immediately changes the value
1830 of the transposition in all current staves and sets a new default
1831 value which will be applied to all staves.
1833 The opposite command, @code{\unset}, effectively removes the
1834 property from the context, which causes most properties to
1835 revert to their default value. Usually @code{\unset} is not
1836 required as a new @code{\set} command will achieve what is
1839 The @code{\set} and @code{\unset} commands can appear anywhere
1840 in the input file and will take effect from the time they are
1841 encountered until the end of the score or until the property is
1842 @code{\set} or @code{\unset} again. Let's try changing the
1843 font size, which affects the size of the note heads (among
1844 other things) several times. The change is from the default
1845 value, not the most recently set value.
1847 @lilypond[quote,verbatim,ragged-right]
1850 % make note heads smaller
1853 % make note heads larger
1854 \set fontSize = #2.5
1856 % return to default size
1862 We have now seen how to set the values of several different types of
1863 property. Note that integers and numbers are always preceded by a
1864 hash sign, @code{#}, while a true or false value is specified by
1865 @code{##t} and @code{##f}, with two hash signs. A text property
1866 should be enclosed in double quotation signs, as above, although we
1867 shall see later that text can actually be specified in a much more
1868 general way by using the very powerful @code{\markup} command.
1870 @subsubheading Setting context properties with @code{\with}
1874 @cindex context properties, setting with \with
1876 The default value of context properties may be set at the time the
1877 context is created. Sometimes this is a clearer way of setting a
1878 property value if it is to remain fixed for the duration of
1879 the context. When a context is created with a @code{\new}
1880 command it may be followed immediately by a @code{\with @{ .. @}}
1881 block in which the default property values are set. For example,
1882 if we wish to suppress the printing of extra naturals for the
1883 duration of a staff we would write:
1886 \new Staff \with @{ extraNatural = ##f @}
1892 @lilypond[quote,verbatim,ragged-right]
1896 gisis'4 gis aeses aes
1899 \new Staff \with { extraNatural = ##f } {
1901 gisis'4 gis aeses aes
1907 Properties set in this way may still be changed dynamically using
1908 @code{\set} and returned to the default value set in the
1909 @code{\with} block with @code{\unset}.
1911 @cindex fontSize, default and setting
1913 So if the @code{fontSize} property is set in a @code{\with} clause
1914 it sets the default value of the font size. If it is later changed
1915 with @code{\set}, this new default value may be restored with the
1916 @code{\unset fontSize} command.
1918 @subsubheading Setting context properties with @code{\context}
1920 @cindex context properties, setting with \context
1924 The values of context properties may be set in @emph{all} contexts
1925 of a particular type, such as all @code{Staff} contexts, with a single
1926 command. The context type is identified by using its
1927 type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
1928 The statement which sets the property value is the same as that in a
1929 @code{\with} block, introduced above. It is placed in a
1930 @code{\context} block within a @code{\layout} block. Each
1931 @code{\context} block will affect all contexts of the type specified
1932 throughout the @code{\score} or @code{\book} block in which the
1933 @code{\layout} block appears. Here is an example to show the format:
1935 @lilypond[verbatim,quote]
1951 If the property override is to be applied to all staves
1954 @lilypond[quote,verbatim]
1959 gisis'4 gis aeses aes
1964 gisis'4 gis aeses aes
1970 \Score extraNatural = ##f
1977 Context properties set in this way may be overridden for particular
1978 instances of contexts by statements in a @code{\with} block, and by
1979 @code{\set} commands embedded in music statements.
1984 @ruser{Changing context default settings}.
1985 @ruser{The set command}.
1987 Internals Reference:
1988 @rinternals{Contexts},
1989 @rinternals{Tunable context properties}.
1992 @node Adding and removing engravers
1993 @subsection Adding and removing engravers
1995 @cindex engravers, adding
1996 @cindex adding engravers
1997 @cindex engravers, removing
1998 @cindex removing engravers
2005 We have seen that contexts each contain several engravers, each
2006 of which is responsible for producing a particular part of the
2007 output, like bar lines, staves, note heads, stems, etc. If an
2008 engraver is removed from a context, it can no longer produce its
2009 output. This is a crude way of modifying the output, but it
2010 can sometimes be useful.
2012 @subsubheading Changing a single context
2014 To remove an engraver from a single context we use the
2015 @code{\with} command placed immediately after the context creation
2016 command, as in the previous section.
2018 As an illustration, let's repeat an example from the previous section
2019 with the staff lines removed. Remember that the staff lines are
2020 produced by the @code{Staff_symbol_engraver}.
2022 @lilypond[quote,verbatim,ragged-right]
2024 \remove "Staff_symbol_engraver"
2028 \set fontSize = #-4 % make note heads smaller
2030 \set fontSize = #2.5 % make note heads larger
2032 \unset fontSize % return to default size
2037 @cindex ambitus engraver
2039 Engravers can also be added to individual contexts.
2040 The command to do this is
2042 @code{\consists @var{Engraver_name}},
2045 placed inside a @code{\with} block. Some vocal scores have an ambitus
2046 placed at the beginning of a staff to indicate the range of notes in
2047 that staff -- see @rglos{ambitus}. The ambitus is produced by the
2048 @code{Ambitus_engraver}, which is not normally included in any
2049 context. If we add it to the @code{Voice} context, it calculates the
2050 range from that voice only:
2052 @lilypond[quote,verbatim,ragged-right]
2055 \consists "Ambitus_engraver"
2072 but if we add the ambitus engraver to the
2073 @code{Staff} context, it calculates the range from all
2074 the notes in all the voices on that staff:
2076 @lilypond[quote,verbatim,ragged-right]
2078 \consists "Ambitus_engraver"
2096 @subsubheading Changing all contexts of the same type
2101 The examples above show how to remove or add engravers to
2102 individual contexts. It is also possible to remove or add
2103 engravers to every context of a specific type by placing the
2104 commands in the appropriate context in a @code{\layout}
2105 block. For example, if we wanted to show an ambitus for every
2106 staff in a four-staff score, we could write
2108 @lilypond[quote,verbatim,ragged-right]
2137 \consists "Ambitus_engraver"
2144 The values of context properties may also be set
2145 for all contexts of a particular type by including the
2146 @code{\set} command in a @code{\context} block in the
2150 Notation Reference: @ruser{Modifying context plug-ins},
2151 @ruser{Changing context default settings}.
2154 The @code{Stem_engraver} and @code{Beam_engraver} attach their
2155 objects to note heads. If the @code{Note_heads_engraver} is removed
2156 no note heads are produced and therefore no stems or beams are created
2160 @node Extending the templates
2161 @section Extending the templates
2163 You've read the tutorial, you know how to write music, you
2164 understand the fundamental concepts. But how can you
2165 get the staves that you want? Well, you can find lots of
2166 templates (see @ref{Templates}) which may give you a start.
2167 But what if you want something that isn't covered there? Read on.
2170 * Soprano and cello::
2171 * Four-part SATB vocal score::
2172 * Building a score from scratch::
2173 * Saving typing with variables and functions::
2174 * Scores and parts::
2177 @node Soprano and cello
2178 @subsection Soprano and cello
2180 @cindex template, modifying
2181 @cindex modifying templates
2183 Start off with the template that seems closest to what you want to
2184 end up with. Let's say that you want to write something for
2185 soprano and cello. In this case, we would start with the
2186 @q{Notes and lyrics} template (for the soprano part).
2189 \version @w{"@version{}"}
2191 melody = \relative @{
2198 text = \lyricmode @{
2204 \new Voice = "one" @{
2208 \new Lyrics \lyricsto "one" \text
2215 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2218 \version @w{"@version{}"}
2220 melody = \relative @{
2234 We don't need two @code{\version} commands. We'll need the
2235 @code{melody} section. We don't want two @code{\score} sections
2236 -- if we had two @code{\score}s, we'd get the two parts separately.
2237 We want them together, as a duet. Within the @code{\score}
2238 section, we don't need two @code{\layout} or @code{\midi}.
2240 If we simply cut and paste the @code{melody} section, we would
2241 end up with two @code{melody} definitions. This would not generate
2242 an error, but the second one would be used for both melodies.
2243 So let's rename them to make them distinct. We'll call the
2244 section for the soprano @code{sopranoMusic} and the section for
2245 the cello @code{celloMusic}. While we're doing this, let's rename
2246 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2247 instances of all these names -- both the initial definition (the
2248 @code{melody = \relative c' @{ } part) and the name's use (in the
2249 @code{\score} section).
2251 While we're doing this, let's change the cello part's staff --
2252 celli normally use bass clef. We'll also give the cello some
2256 \version @w{"@version{}"}
2258 sopranoMusic = \relative @{
2265 sopranoLyrics = \lyricmode @{
2269 celloMusic = \relative @{
2278 \new Voice = "one" @{
2282 \new Lyrics \lyricsto "one" \sopranoLyrics
2289 This is looking promising, but the cello part won't appear in the
2290 score -- we haven't used it in the @code{\score} section. If we
2291 want the cello part to appear under the soprano part, we need to add
2294 \new Staff \celloMusic
2298 underneath the soprano stuff. We also need to add @code{<<} and
2299 @code{>>} around the music -- that tells LilyPond that there's
2300 more than one thing (in this case, two @code{Staves}) happening
2301 at once. The @code{\score} looks like this now:
2303 @c Indentation in this example is deliberately poor
2308 \new Voice = "one" @{
2312 \new Lyrics \lyricsto "one" \sopranoLyrics
2314 \new Staff \celloMusic
2322 This looks a bit messy; the indentation is messed up now. That is
2323 easily fixed. Here's the complete soprano and cello template.
2325 @lilypond[quote,verbatim,ragged-right,addversion]
2326 sopranoMusic = \relative {
2333 sopranoLyrics = \lyricmode {
2337 celloMusic = \relative {
2347 \new Voice = "one" {
2351 \new Lyrics \lyricsto "one" \sopranoLyrics
2353 \new Staff \celloMusic
2362 The starting templates can be found in the @q{Templates} appendix,
2363 see @ref{Single staff templates}.
2366 @node Four-part SATB vocal score
2367 @subsection Four-part SATB vocal score
2369 @cindex template, SATB
2370 @cindex SATB template
2372 Most vocal scores of music written for four-part mixed choir
2373 with orchestral accompaniment such as Mendelssohn's Elijah or
2374 Handel's Messiah have the choral music and words on four
2375 staves, one for each of SATB, with a piano reduction of the
2376 orchestral accompaniment underneath. Here's an example
2377 from Handel's Messiah:
2379 @c The following should appear as music without code
2380 @lilypond[quote,ragged-right]
2381 global = { \key d \major \time 4/4 }
2383 sopranoMusic = \relative {
2385 r4 d''2 a4 | d4. d8 a2 | cis4 d cis2 |
2387 sopranoWords = \lyricmode {
2388 Wor -- thy | is the lamb | that was slain |
2391 altoMusic = \relative {
2393 r4 a'2 a4 | fis4. fis8 a2 | g4 fis e2 |
2395 altoWords = \sopranoWords
2397 tenorMusic = \relative {
2399 r4 fis'2 e4 | d4. d8 d2 | e4 a, cis2 |
2401 tenorWords = \sopranoWords
2403 bassMusic = \relative {
2405 r4 d'2 cis4 | b4. b8 fis2 | e4 d a'2 |
2407 bassWords = \sopranoWords
2412 r4 <a' d fis>2 <a e' a>4 |
2413 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2414 <g cis g'>4 <a d fis> <a cis e>2 |
2420 <d, d'>4 <d d'>2 <cis cis'>4 |
2421 <b b'>4. <b' b'>8 <fis fis'>2 |
2422 <e e'>4 <d d'> <a' a'>2 |
2426 << % combine ChoirStaff and PianoStaff in parallel
2428 \new Staff = "sopranos" <<
2429 \set Staff.instrumentName = #"Soprano"
2430 \new Voice = "sopranos" {
2435 \new Lyrics \lyricsto "sopranos" {
2438 \new Staff = "altos" <<
2439 \set Staff.instrumentName = #"Alto"
2440 \new Voice = "altos" {
2445 \new Lyrics \lyricsto "altos" { \altoWords }
2446 \new Staff = "tenors" <<
2447 \set Staff.instrumentName = #"Tenor"
2448 \new Voice = "tenors" {
2453 \new Lyrics \lyricsto "tenors" { \tenorWords }
2454 \new Staff = "basses" <<
2455 \set Staff.instrumentName = #"Bass"
2456 \new Voice = "basses" {
2461 \new Lyrics \lyricsto "basses" {
2466 \set PianoStaff.instrumentName = #"Piano"
2467 \new Staff = "upper" \upper
2468 \new Staff = "lower" \lower
2474 None of the templates provides this layout exactly. The nearest is
2475 @ref{SATB vocal score and automatic piano reduction} -- but we need
2476 to change the layout and add a piano
2477 accompaniment which is not derived automatically from the vocal parts.
2478 The variables holding the music and words for the vocal parts are
2479 fine, but we shall need to add variables for the piano reduction.
2481 The order in which the contexts appear in the ChoirStaff of the
2482 template do not correspond with the order in the vocal score shown
2483 above. We need to rearrange them so there are four staves with the
2484 words written directly underneath the notes for each part. All the
2485 voices should be @code{\voiceOne}, which is the default, so the
2486 @code{\voiceXXX} commands should be removed. We also need to specify
2487 the tenor clef for the tenors. The way in which lyrics are specified
2488 in the template has not yet been encountered so we need to use the
2489 method with which we are familiar. We should also add the names of
2492 Doing this gives for our ChoirStaff:
2496 \new Staff = "sopranos" <<
2497 \set Staff.instrumentName = #"Soprano"
2498 \new Voice = "sopranos" @{
2503 \new Lyrics \lyricsto "sopranos" @{
2506 \new Staff = "altos" <<
2507 \set Staff.instrumentName = #"Alto"
2508 \new Voice = "altos" @{
2513 \new Lyrics \lyricsto "altos" @{
2516 \new Staff = "tenors" <<
2517 \set Staff.instrumentName = #"Tenor"
2518 \new Voice = "tenors" @{
2523 \new Lyrics \lyricsto "tenors" @{
2526 \new Staff = "basses" <<
2527 \set Staff.instrumentName = #"Bass"
2528 \new Voice = "basses" @{
2533 \new Lyrics \lyricsto "basses" @{
2539 Next we must work out the piano part. This is
2540 easy - we just pull out the piano part from the
2541 @q{Solo piano} template:
2545 \set PianoStaff.instrumentName = #"Piano "
2546 \new Staff = "upper" \upper
2547 \new Staff = "lower" \lower
2551 and add the variable definitions for @code{upper}
2554 The ChoirStaff and PianoStaff must be combined
2555 using angle brackets as we want them to be
2556 stacked one above the other:
2559 << % combine ChoirStaff and PianoStaff one above the other
2561 \new Staff = "sopranos" <<
2562 \new Voice = "sopranos" @{
2567 \new Lyrics \lyricsto "sopranos" @{
2570 \new Staff = "altos" <<
2571 \new Voice = "altos" @{
2576 \new Lyrics \lyricsto "altos" @{
2579 \new Staff = "tenors" <<
2580 \clef "G_8" % tenor clef
2581 \new Voice = "tenors" @{
2586 \new Lyrics \lyricsto "tenors" @{
2589 \new Staff = "basses" <<
2591 \new Voice = "basses" @{
2596 \new Lyrics \lyricsto "basses" @{
2602 \set PianoStaff.instrumentName = #"Piano"
2603 \new Staff = "upper" \upper
2604 \new Staff = "lower" \lower
2609 Combining all these together and adding the music
2610 for the three bars of the example above gives:
2612 @lilypond[quote,verbatim,ragged-right,addversion]
2613 global = { \key d \major \time 4/4 }
2614 sopranoMusic = \relative {
2616 r4 d''2 a4 | d4. d8 a2 | cis4 d cis2 |
2618 sopranoWords = \lyricmode {
2619 Wor -- thy | is the lamb | that was slain |
2621 altoMusic = \relative {
2623 r4 a'2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2625 altoWords = \sopranoWords
2626 tenorMusic = \relative {
2628 r4 fis'2 e4 | d4. d8 d2 | e4 a, cis2 |
2630 tenorWords = \sopranoWords
2631 bassMusic = \relative {
2633 r4 d'2 cis4 | b4. b8 fis2 | e4 d a'2 |
2635 bassWords = \sopranoWords
2639 r4 <a' d fis>2 <a e' a>4 |
2640 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2641 <g cis g'>4 <a d fis> <a cis e>2 |
2646 <d, d'>4 <d d'>2 <cis cis'>4 |
2647 <b b'>4. <b' b'>8 <fis fis'>2 |
2648 <e e'>4 <d d'> <a' a'>2 |
2652 << % combine ChoirStaff and PianoStaff in parallel
2654 \new Staff = "sopranos" <<
2655 \set Staff.instrumentName = #"Soprano"
2656 \new Voice = "sopranos" {
2661 \new Lyrics \lyricsto "sopranos" {
2664 \new Staff = "altos" <<
2665 \set Staff.instrumentName = #"Alto"
2666 \new Voice = "altos" {
2671 \new Lyrics \lyricsto "altos" {
2674 \new Staff = "tenors" <<
2675 \set Staff.instrumentName = #"Tenor"
2676 \new Voice = "tenors" {
2681 \new Lyrics \lyricsto "tenors" {
2684 \new Staff = "basses" <<
2685 \set Staff.instrumentName = #"Bass"
2686 \new Voice = "basses" {
2691 \new Lyrics \lyricsto "basses" {
2697 \set PianoStaff.instrumentName = #"Piano "
2698 \new Staff = "upper" \upper
2699 \new Staff = "lower" \lower
2706 @node Building a score from scratch
2707 @subsection Building a score from scratch
2709 @cindex template, writing your own
2710 @cindex example of writing a score
2711 @cindex writing a score, example
2712 @cindex score, example of writing
2714 After gaining some facility with writing LilyPond code, you
2715 may find that it is easier to build a score from scratch
2716 rather than modifying one of the templates. You can also
2717 develop your own style this way to suit the sort of music you
2718 like. Let's see how to put together the score for an organ
2719 prelude as an example.
2721 We begin with a header section. Here go the title, name
2722 of composer, etc, then come any variable definitions, and
2723 finally the score block. Let's start with these in outline
2724 and fill in the details later.
2726 We'll use the first two bars of Bach's prelude
2727 based on @emph{Jesu, meine Freude} which is written for two
2728 manuals and pedal organ. You can see these two bars of music
2729 at the bottom of this section. The top manual part has two voices,
2730 the lower and pedal organ one each. So we need four
2731 music definitions and one to define the time signature
2735 \version @w{"@version{}"}
2737 title = "Jesu, meine Freude"
2738 composer = "J S Bach"
2740 keyTime = @{ \key c \minor \time 4/4 @}
2741 ManualOneVoiceOneMusic = @{ s1 @}
2742 ManualOneVoiceTwoMusic = @{ s1 @}
2743 ManualTwoMusic = @{ s1 @}
2744 PedalOrganMusic = @{ s1 @}
2750 For now we've just used a spacer note, @code{s1},
2751 instead of the real music. We'll add that later.
2753 Next let's see what should go in the score block.
2754 We simply mirror the staff structure we want.
2755 Organ music is usually written on three staves,
2756 one for each manual and one for the pedals. The
2757 manual staves should be bracketed together, so we
2758 need to use a PianoStaff for them. The first
2759 manual part needs two voices and the second manual
2764 \new Staff = "ManualOne" <<
2766 \ManualOneVoiceOneMusic
2769 \ManualOneVoiceTwoMusic
2771 >> % end ManualOne Staff context
2772 \new Staff = "ManualTwo" <<
2776 >> % end ManualTwo Staff context
2777 >> % end PianoStaff context
2780 Next we need to add a staff for the pedal organ.
2781 This goes underneath the PianoStaff, but it must
2782 be simultaneous with it, so we need angle brackets
2783 around the two. Missing these out would generate
2784 an error in the log file. It's a common mistake
2785 which you'll make sooner or later! Try copying
2786 the final example at the end of this section,
2787 remove these angle brackets, and compile it to
2788 see what errors it generates.
2791 << % PianoStaff and Pedal Staff must be simultaneous
2793 \new Staff = "ManualOne" <<
2795 \ManualOneVoiceOneMusic
2798 \ManualOneVoiceTwoMusic
2800 >> % end ManualOne Staff context
2801 \new Staff = "ManualTwo" <<
2805 >> % end ManualTwo Staff context
2806 >> % end PianoStaff context
2807 \new Staff = "PedalOrgan" <<
2815 It is not necessary to use the simultaneous construct
2816 @code{<< .. >>} for the manual two staff and the pedal organ staff,
2817 since they contain only one music expression, but it does no harm,
2818 and always using angle brackets after @code{\new Staff} is a good
2819 habit to cultivate in case there are multiple voices. The opposite
2820 is true for Voices: these should habitually be followed by braces
2821 @code{@{ .. @}} in case your music is coded in several variables
2822 which need to run consecutively.
2824 Let's add this structure to the score block, and adjust the indenting.
2825 We also add the appropriate clefs, ensure stems, ties and slurs in
2826 each voice on the upper staff point to the right direction with
2827 @code{\voiceOne} and @code{\voiceTwo}, and enter the key and time
2828 signature to each staff using our predefined variable, @code{\keyTime}.
2832 << % PianoStaff and Pedal Staff must be simultaneous
2834 \new Staff = "ManualOne" <<
2835 \keyTime % set key and time signature
2839 \ManualOneVoiceOneMusic
2843 \ManualOneVoiceTwoMusic
2845 >> % end ManualOne Staff context
2846 \new Staff = "ManualTwo" <<
2852 >> % end ManualTwo Staff context
2853 >> % end PianoStaff context
2854 \new Staff = "PedalOrgan" <<
2860 >> % end PedalOrgan Staff
2862 @} % end Score context
2865 @cindex stretchability of staves
2866 @cindex staves, stretchability
2868 The above layout of the organ staves is almost perfect; however,
2869 there is a slight defect which is not visible by looking at just a
2870 single system: The distance of the pedal staff to the left hand staff
2871 should behave approximately the same as the right hand staff to the
2872 left hand staff. In particular, the stretchability of staves in a
2873 @code{PianoStaff} context is limited (so that the distance between
2874 the staves for the left and right hand can't become too large), and
2875 the pedal staff should behave similarly.
2877 @cindex sub-properties
2878 @cindex properties, sub-properties
2879 @cindex graphical objects
2880 @cindex objects, graphical
2883 Stretchability of staves can be controlled with the
2884 @code{staff-staff-spacing} property of the
2885 @code{VerticalAxisGroup} @q{graphical object} (commonly called
2886 @q{grob}s within the lilypond documentation) -- don't worry about
2887 the details right now; this is fully explained later. For the
2888 curious, have a look at @ruser{Overview of modifying properties}.
2889 In this case, we want to modify the @code{stretchability}
2890 sub-property only. Again, for the curious, you can find the
2891 default values for the staff-staff-spacing property
2892 in file @file{scm/define-grobs.scm} by looking up the definition
2893 of the @code{VerticalAxisGroup} grob. The value for
2894 @code{stretchability} is taken from the definition of the
2895 @code{PianoStaff} context (in file @file{ly/engraver-init.ly})
2896 so that the values are identical.
2900 << % PianoStaff and Pedal Staff must be simultaneous
2902 \new Staff = "ManualOne" <<
2903 \keyTime % set key and time signature
2907 \ManualOneVoiceOneMusic
2911 \ManualOneVoiceTwoMusic
2913 >> % end ManualOne Staff context
2914 \new Staff = "ManualTwo" \with @{
2915 \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
2922 >> % end ManualTwo Staff context
2923 >> % end PianoStaff context
2924 \new Staff = "PedalOrgan" <<
2930 >> % end PedalOrgan Staff
2932 @} % end Score context
2934 That completes the structure. Any three-staff organ music
2935 will have a similar structure, although the number of voices
2936 may vary. All that remains now
2937 is to add the music, and combine all the parts together.
2939 @lilypond[quote,verbatim,ragged-right,addversion]
2941 title = "Jesu, meine Freude"
2942 composer = "J S Bach"
2944 keyTime = { \key c \minor \time 4/4 }
2945 ManualOneVoiceOneMusic = \relative {
2949 ManualOneVoiceTwoMusic = \relative {
2950 ees'16 d ees8~ 16 f ees d c8 d~ d c~ |
2951 8 c4 b8 c8. g16 c b c d |
2953 ManualTwoMusic = \relative {
2954 c'16 b c8~ 16 b c g a8 g~ 16 g aes ees |
2955 f16 ees f d g aes g f ees d ees8~ 16 f ees d |
2957 PedalOrganMusic = \relative {
2958 r8 c16 d ees d ees8~ 16 a, b g c b c8 |
2959 r16 g ees f g f g8 c,2 |
2963 << % PianoStaff and Pedal Staff must be simultaneous
2965 \new Staff = "ManualOne" <<
2966 \keyTime % set key and time signature
2970 \ManualOneVoiceOneMusic
2974 \ManualOneVoiceTwoMusic
2976 >> % end ManualOne Staff context
2977 \new Staff = "ManualTwo" \with {
2978 \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
2985 >> % end ManualTwo Staff context
2986 >> % end PianoStaff context
2987 \new Staff = "PedalOrgan" <<
2993 >> % end PedalOrgan Staff context
2995 } % end Score context
3002 @node Saving typing with variables and functions
3003 @subsection Saving typing with variables and functions
3008 By this point, you've seen this kind of thing:
3010 @lilypond[quote,verbatim,ragged-right]
3011 hornNotes = \relative { c''4 b dis c }
3020 You may even realize that this could be useful in minimalist music:
3022 @lilypond[quote,verbatim,ragged-right]
3023 fragmentA = \relative { a'4 a8. b16 }
3024 fragmentB = \relative { a'8. gis16 ees4 }
3026 violin = \new Staff {
3027 \fragmentA \fragmentA |
3028 \fragmentB \fragmentA |
3038 However, you can also use these variables (also known as
3039 macros, or user-defined commands) for tweaks:
3041 @c TODO Avoid padtext - not needed with skylining
3042 @lilypond[quote,verbatim,ragged-right]
3043 dolce = \markup { \italic \bold dolce }
3045 padText = { \once \override TextScript.padding = #5.0 }
3047 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
3050 violin = \relative {
3052 c''4._\dolce b8 a8 g a b |
3054 c4.^"hi there!" d8 e' f g d |
3055 c,4.\fthenp b8 c4 c-. |
3063 \layout { ragged-right = ##t }
3067 These variables are obviously useful for saving
3068 typing. But they're worth considering even if you
3069 only use them once -- they reduce complexity. Let's
3070 look at the previous example without any
3071 variables. It's a lot harder to read, especially
3075 violin = \relative @{
3077 c''4._\markup @{ \italic \bold dolce @} b8 a8 g a b |
3078 \once \override TextScript.padding = #5.0
3079 c4.^"hi there!" d8 e' f g d |
3081 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p
3088 @c TODO Replace the following with a better example -td
3089 @c Skylining handles this correctly without padText
3091 So far we've seen static substitution -- when LilyPond
3092 sees @code{\padText}, it replaces it with the stuff that
3093 we've defined it to be (ie the stuff to the right of
3096 LilyPond can handle non-static substitution, too (you
3097 can think of these as functions).
3099 @lilypond[quote,verbatim,ragged-right]
3101 #(define-music-function
3105 \once \override TextScript.padding = #padding
3109 c'''4^"piu mosso" b a b |
3111 c4^"piu mosso" d e f |
3113 c4^"piu mosso" fis a g |
3117 Using variables is also a good way to reduce work if the
3118 LilyPond input syntax changes (see
3119 @rprogram{Updating files with convert-ly}). If
3120 you have a single definition (such as @code{\dolce}) for all your
3121 input files (see @ref{Style sheets}), then if the syntax changes, you
3122 only need to update your single @code{\dolce} definition,
3123 instead of making changes throughout every @file{.ly} file.
3126 @node Scores and parts
3127 @subsection Scores and parts
3129 In orchestral music, all notes are printed twice. Once in a part for
3130 the musicians, and once in a full score for the conductor. Variables can
3131 be used to avoid double work. The music is entered once, and stored in
3132 a variable. The contents of that variable is then used to generate
3133 both the part and the full score.
3135 It is convenient to define the notes in a special file. For example,
3136 suppose that the file @file{horn-music.ly} contains the following part
3137 of a horn/@/bassoon duo
3140 hornNotes = \relative @{
3142 r4 f8 a | cis4 f | e4 d |
3147 Then, an individual part is made by putting the following in a file
3150 \include "horn-music.ly"
3153 instrument = "Horn in F"
3157 \transpose f c' \hornNotes
3164 \include "horn-music.ly"
3168 substitutes the contents of @file{horn-music.ly} at this position in
3169 the file, so @code{hornNotes} is defined afterwards. The command
3170 @code{\transpose f@tie{}c'} indicates that the argument, being
3171 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
3172 @code{f} is denoted by notated @code{c'}, which corresponds with the
3173 tuning of a normal French Horn in@tie{}F. The transposition can be seen
3174 in the following output
3176 @lilypond[quote,ragged-right]
3177 \transpose f c' \relative {
3179 r4 f8 a | cis4 f | e4 d |
3183 In ensemble pieces, one of the voices often does not play for many
3184 measures. This is denoted by a special rest, the multi-measure
3185 rest. It is entered with a capital @code{R} followed by a duration
3186 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
3187 etc.). By multiplying the
3188 duration, longer rests can be constructed. For example, this rest
3189 takes 3@tie{}measures in 2/4 time
3195 When printing the part, multi-rests
3196 must be condensed. This is done by setting a run-time variable
3199 \set Score.skipBars = ##t
3203 This command sets the property @code{skipBars} in the
3204 @code{Score} context to true (@code{##t}). Prepending the rest and
3205 this option to the music above, leads to the following result
3207 @lilypond[quote,ragged-right]
3208 \transpose f c' \relative {
3210 \set Score.skipBars = ##t
3212 r4 f8 a | cis4 f | e4 d |
3217 The score is made by combining all of the music together. Assuming
3218 that the other voice is in @code{bassoonNotes} in the file
3219 @file{bassoon-music.ly}, a score is made with
3222 \include "bassoon-music.ly"
3223 \include "horn-music.ly"
3226 \new Staff \hornNotes
3227 \new Staff \bassoonNotes
3234 @lilypond[quote,ragged-right]
3240 r4 f8 a | cis4 f | e4 d |
3245 r4 d,8 f | gis4 c | b4 bes |
3246 a8 e f4 | g4 d | gis4 f |