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 c' @{
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
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 c'' { r4 d8\noBeam g, c4 r }
390 text = \lyricmode { And God said, }
391 upper = \relative c'' { <g d g,>2~ <g d g,> }
392 lower = \relative c { b2 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,relative=2]
549 g8\( 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,relative=1]
560 r16[ g \tuplet 3/2 { r16 e'8] }
561 g,16( a \tuplet 3/2 { b16 d) e }
562 g,8[( a \tuplet 3/2 { b8 d) e~] } |
563 \tuplet 5/4 { e32\( a, b d e } a4.\)
567 @node Voices contain music
568 @section Voices contain music
570 Singers need voices to sing, and so does LilyPond.
571 The actual music for all instruments in a score
572 is contained in Voices -- the most fundamental
573 of all LilyPond's concepts.
576 * I'm hearing Voices::
577 * Explicitly instantiating voices::
578 * Voices and vocals::
581 @node I'm hearing Voices
582 @subsection I'm hearing Voices
586 @cindex multiple voices
587 @cindex voices, multiple
588 @cindex Voice context
589 @cindex context, Voice
590 @cindex simultaneous music
591 @cindex music, simultaneous
592 @cindex concurrent music
593 @cindex music, concurrent
594 @cindex voices vs. chords
595 @cindex chords vs. voices
597 The lowest, most fundamental or innermost layers in a LilyPond
598 score are called @q{Voice contexts} or just @q{Voices} for short.
599 Voices are sometimes called @q{layers} in other notation
602 In fact, a Voice layer or context is the only one which can contain
603 music. If a Voice context is not explicitly declared one is created
604 automatically, as we saw at the beginning of this chapter. Some
605 instruments such as an Oboe can play only one note at a time. Music
606 written for such instruments requires just a single voice. Instruments
607 which can play more than one note at a time like the piano will often
608 require multiple voices to encode the different concurrent notes and
609 rhythms they are capable of playing.
611 A single voice can contain many notes in a chord, of course,
612 so when exactly are multiple voices needed? Look first at
613 this example of four chords:
615 @lilypond[quote,verbatim,ragged-right,relative=1]
617 <d g>4 <d fis> <d a'> <d g>
620 This can be expressed using just the single angle bracket chord
621 symbols, @code{< ... >}, and for this just a single voice is
622 needed. But suppose the F-sharp were actually an eighth-note
623 followed by an eighth-note G, a passing note on the way to the A?
624 Now we have two notes which start at the same time but have
625 different durations: the quarter-note D and the eighth-note
626 F-sharp. How are these to be coded? They cannot be written as
627 a chord because all the notes in a chord must have the same
628 duration. And they cannot be written as two sequential notes
629 as they need to start at the same time. This is when two
632 Let us see how this is done in LilyPond input syntax.
637 The easiest way to enter fragments with more than one voice on a
638 staff is to enter each voice as a sequence (with @code{@{...@}}),
639 and combine them simultaneously with angle brackets, @code{<<...>>}.
640 The fragments must also be separated with double backward slashes,
641 @code{\\}, to place them in separate voices. Without these, the
642 notes would be entered into a single voice, which would usually
643 cause errors. This technique is particularly suited to pieces of
644 music which are largely homophonic with occasional short sections
647 Here's how we split the chords above into two voices and add both
648 the passing note and a slur:
650 @lilypond[quote,verbatim,ragged-right,relative=2]
652 % Voice "1" Voice "2"
653 << { g4 fis8( g) a4 g } \\ { d4 d d d } >>
656 Notice how the stems of the second voice now point down.
658 Here's another simple example:
660 @lilypond[quote,verbatim,ragged-right,relative=2]
662 % Voice "1" Voice "2"
663 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
664 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
665 << { a2. r4 } \\ { fis2. s4 } >> |
668 It is not necessary to use a separate @code{<< \\ >>} construct
669 for each bar. For music with few notes in each bar this layout
670 can help the legibility of the code, but if there are many
671 notes in each bar it may be better to split out each voice
672 separately, like this:
674 @lilypond[quote,verbatim,ragged-right,relative=2]
690 @cindex voices, naming
691 @cindex voices crossing brackets
692 @cindex slurs crossing brackets
693 @cindex ties crossing brackets
695 This example has just two voices, but the same construct may be
696 used to encode three or more voices by adding more back-slash
699 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
700 The first contexts set the @emph{outer} voices, the highest
701 voice in context @code{"1"} and the lowest voice in context
702 @code{"2"}. The inner voices go in contexts @code{"3"} and
703 @code{"4"}. In each of these contexts, the vertical direction
704 of slurs, stems, ties, dynamics etc., is set appropriately.
706 @lilypond[quote,verbatim]
707 \new Staff \relative c' {
710 % Voice "1" Voice "2" Voice "3"
711 << { g4 f e } \\ { r8 e4 d c8~ } >> |
712 << { d2 e } \\ { c8 b16 a b8 g~ g2 } \\ { s4 b c2 } >> |
716 These voices are all separate from the main voice that contains
717 the notes just outside the @code{<< .. >>} construct. Let's call
718 this the @emph{simultaneous construct}. Slurs and ties may only
719 connect notes within the same voice, so slurs and ties cannot go
720 into or out of a simultaneous construct. Conversely,
721 parallel voices from separate simultaneous constructs on the same
722 staff are the same voice. Other voice-related properties also
723 carry across simultaneous constructs. Here is the same example,
724 with different colors and note heads for each voice. Note that
725 changes in one voice do not affect other voices, but they do
726 persist in the same voice later. Note also that tied notes may be
727 split across the same voices in two constructs, shown here in the
730 @lilypond[quote,verbatim]
731 \new Staff \relative c' {
750 { c8 b16 a b8 g~ g2 }
760 @funindex \voiceOneStyle
761 @funindex \voiceTwoStyle
762 @funindex \voiceThreeStyle
763 @funindex \voiceFourStyle
764 @funindex \voiceNeutralStyle
766 The commands @code{\voiceXXXStyle} are mainly intended for use in
767 educational documents such as this one. They modify the color
768 of the note head, the stem and the beams, and the style of the
769 note head, so that the voices may be easily distinguished.
770 Voice one is set to red diamonds, voice two to blue triangles,
771 voice three to green crossed circles, and voice four (not used
772 here) to magenta crosses; @code{\voiceNeutralStyle} (also not
773 used here) reverts the style back to the default.
774 We shall see later how commands like these may be created by the
776 See @ref{Visibility and color of objects} and
777 @ref{Using variables for tweaks}.
779 @cindex polyphony and relative note entry
780 @cindex relative note entry and polyphony
782 Polyphony does not change the relationship of notes within a
783 @code{\relative} block. Each note is still calculated relative to
784 the note immediately preceding it, or to the first note of the
785 preceding chord. So in
788 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
792 @code{noteB} is relative to @code{noteA} @*
793 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
794 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
796 @code{noteE} is relative to @code{noteD}, not @code{noteA}.
798 An alternative way, which may be clearer if the notes in the
799 voices are widely separated, is to place a @code{\relative}
800 command at the start of each voice:
803 \relative c' @{ noteA ... @}
805 \relative c'' @{ < noteB noteC > ... @}
807 \relative g' @{ noteD ... @}
809 \relative c' @{ noteE ... @}
812 Let us finally analyze the voices in a more complex piece of music.
813 Here are the notes from the first two bars of the second of Chopin's
814 Deux Nocturnes, Op 32. This example will be used at later stages in
815 this and the next chapter to illustrate several techniques for
816 producing notation, so please ignore for now anything in the
817 underlying code which looks mysterious and concentrate just on the
818 music and the voices -- the complications will all be explained in
821 @c The following should appear as music without code
822 @lilypond[quote,ragged-right]
823 \new Staff \relative c'' {
829 % Ignore these for now - they are explained in Ch 4
830 \once \override NoteColumn.ignore-collision = ##t
832 \once \override NoteColumn.force-hshift = #0.5
838 \override NoteColumn.force-hshift = #0
846 The direction of the stems is often used to indicate the continuity of
847 two simultaneous melodic lines. Here the stems of the highest notes
848 are all pointing up and the stems of the lower notes are all pointing
849 down. This is the first indication that more than one voice is
852 But the real need for multiple voices arises when notes
853 which start at the same time have different durations.
854 Look at the notes which start at beat three in the first
855 bar. The A-flat is a dotted quarter note, the F is a
856 quarter note and the D-flat is a half note. These
857 cannot be written as a chord as all the notes in a chord
858 must have the same duration. Neither can they be written
859 as sequential notes, as they must start at the same time.
860 This section of the bar requires three voices, and the
861 normal practice would be to write the whole bar as three
862 voices, as shown below, where we have used different note heads
863 and colors for the three voices. Again, the code behind this
864 example will be explained later, so ignore anything you do
867 @c The following should appear as music without code
868 @c The three voice styles should be defined in -init
869 @lilypond[quote,ragged-right]
870 \new Staff \relative c'' {
879 % Ignore these for now - they are explained in Ch 4
880 \once \override NoteColumn.ignore-collision = ##t
882 \once \override NoteColumn.force-hshift = #0.5
885 \\ % No Voice three (we want stems down)
888 \override NoteColumn.force-hshift = #0
897 Let us try to encode this music from scratch. As we
898 shall see, this encounters some difficulties. We begin as
899 we have learnt, using the @code{<< \\ >>} construct to
900 enter the music of the first bar in three voices:
902 @lilypond[quote,verbatim,ragged-right]
903 \new Staff \relative c'' {
906 { c2 aes4. bes8 } \\ { <ees, c>2 des } \\ { aes'2 f4 fes }
913 @cindex voices and stem directions
914 @cindex stem directions and voices
917 The stem directions are automatically assigned with the
918 odd-numbered voices taking upward stems and the even-numbered
919 voices downward ones. The stems for voices 1 and 2 are right,
920 but the stems in voice 3 should go down in this particular piece
921 of music. We can correct this by skipping voice three
922 and placing the music in voice four. This is done by simply
923 adding another pair of @code{\\}.
925 @lilypond[quote,verbatim,ragged-right]
926 \new Staff \relative c'' {
932 \\ % Omit Voice three
941 We see that this fixes the stem direction, but the horizontal
942 placement of notes is not what we want. LilyPond shifts the
943 inner notes when they or their stems would collide with outer
944 voices, but this is not appropriate for piano music. In other
945 situations, the shifts LilyPond applies might fail to clear
946 the collisions. LilyPond provides several ways to adjust the
947 horizontal placing of notes. We are not quite ready yet to see
948 how to correct this, so we shall leave this problem until a
949 later section --- see the @code{force-hshift} property in
950 @ref{Fixing overlapping notation}.
952 @warning{Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be
953 created @q{across} voices.}
957 Notation Reference: @ruser{Multiple voices}.
960 @node Explicitly instantiating voices
961 @subsection Explicitly instantiating voices
967 @funindex \voiceThree
974 @cindex voice contexts, creating
976 Voice contexts can also be created manually
977 inside a @code{<< >>} block to create polyphonic music, using
978 @code{\voiceOne} @dots{} @code{\voiceFour} to indicate the required
979 directions of stems, slurs, etc. In longer scores this method
980 is clearer, as it permits the voices to be separated and to be
981 given more descriptive names.
983 Specifically, the construct @code{<< \\ >>} which we used in
984 the previous section:
989 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
999 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
1000 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
1004 Both of the above would produce
1006 @c The following example should not display the code
1007 @lilypond[ragged-right,quote]
1009 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
1010 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
1014 @cindex voices, reverting to single
1015 @cindex reverting to a single voice
1017 The @code{\voiceXXX} commands set the direction of stems, slurs,
1018 ties, articulations, text annotations, augmentation dots of dotted
1019 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
1020 make these objects point upwards, while @code{\voiceTwo} and
1021 @code{\voiceFour} make them point downwards. These commands also
1022 generate a horizontal shift for each voice when this is required
1023 to avoid clashes of note heads. The command @code{\oneVoice}
1024 reverts the settings back to the normal values for a single voice.
1026 Let us see in some simple examples exactly what effect
1027 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
1028 markup, ties, slurs, and dynamics:
1030 @lilypond[quote,ragged-right,verbatim]
1032 % Default behavior or behavior after \oneVoice
1033 c4 d8~ d e4( f | g4 a) b-> c |
1037 @lilypond[quote,ragged-right,verbatim]
1040 c4 d8~ d e4( f | g4 a) b-> c |
1042 c,4 d8~ d e4( f | g4 a) b-> c |
1046 @lilypond[quote,ragged-right,verbatim]
1049 c4 d8~ d e4( f | g4 a) b-> c |
1051 c,4 d8~ d e4( f | g4 a) b-> c |
1055 Now let's look at three different ways to notate the same passage of
1056 polyphonic music, each of which is advantageous in different
1057 circumstances, using the example from the previous section.
1059 An expression that appears directly inside a @code{<< >>} belongs to the
1060 main voice (but, note, @strong{not} in a @code{<< \\ >>} construct).
1061 This is useful when extra voices appear while the main voice is playing.
1062 Here is a more correct rendition of our example. The red diamond-shaped
1063 notes demonstrate that the main melody is now in a single voice context,
1064 permitting a phrasing slur to be drawn over them.
1066 @lilypond[quote,ragged-right,verbatim]
1067 \new Staff \relative c' {
1069 % This section is homophonic
1071 % Start simultaneous section of three voices
1073 % Continue the main voice in parallel
1074 { g4 f e | d2 e) | }
1075 % Initiate second voice
1077 % Set stems, etc., down
1079 r8 e4 d c8~ | c8 b16 a b8 g~ g2 |
1081 % Initiate third voice
1083 % Set stems, etc, up
1091 @cindex nesting music expressions
1092 @cindex nesting simultaneous constructs
1093 @cindex nesting voices
1094 @cindex voices, temporary
1095 @cindex voices, nesting
1097 More deeply nested polyphony constructs are possible, and if a
1098 voice appears only briefly this might be a more natural way to
1101 @lilypond[quote,ragged-right,verbatim]
1102 \new Staff \relative c' {
1105 { g4 f e | d2 e) | }
1110 { c8 b16 a b8 g~ g2 | }
1121 @cindex spacing notes
1123 This method of nesting new voices briefly is useful
1124 when only small sections of the music
1125 are polyphonic, but when the whole staff is largely polyphonic
1126 it can be clearer to use multiple voices throughout, using
1127 spacing notes to step over sections where the voice is silent,
1130 @lilypond[quote,ragged-right,verbatim]
1131 \new Staff \relative c' <<
1132 % Initiate first voice
1135 c16^( d e f g4 f e | d2 e) |
1137 % Initiate second voice
1139 % Set stems, etc, down
1141 s4 r8 e4 d c8~ | c8 b16 a b8 g~ g2 |
1143 % Initiate third voice
1145 % Set stems, etc, up
1152 @subsubheading Note columns
1155 @cindex note collisions
1156 @cindex collisions, notes
1157 @cindex shift commands
1164 @funindex \shiftOnnn
1167 Closely spaced notes in a chord, or notes occurring at the same
1168 time in different voices, are arranged in two, occasionally more,
1169 columns to prevent the note heads overlapping. These are called
1170 note columns. There are separate columns for each voice, and
1171 the currently specified voice-dependent shift is applied to the
1172 note column if there would otherwise be a collision. This can
1173 be seen in the example above. In bar 2 the C in voice two is
1174 shifted to the right relative to the D in voice one, and in the
1175 final chord the C in voice three is also shifted to the right
1176 relative to the other notes.
1178 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1179 @code{\shiftOff} commands specify the degree to which notes and
1180 chords of the voice should be shifted if a collision
1181 would otherwise occur. By default, the outer voices (normally
1182 voices one and two) have @code{\shiftOff} specified, while the
1183 inner voices (three and four) have @code{\shiftOn} specified.
1184 When a shift is applied, voices one and three are shifted to
1185 the right and voices two and four to the left.
1187 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1188 levels which may be specified temporarily to resolve collisions
1189 in complex situations -- see @ref{Real music example}.
1191 A note column can contain just one note (or chord) from a voice
1192 with stems up and one note (or chord) from a voice with stems
1193 down. If notes from two voices which have their stems in the
1194 same direction are placed at the same position and both voices
1195 have no shift or the same shift specified, the error message
1196 @qq{Too many clashing note columns} will be produced.
1200 Notation Reference: @ruser{Multiple voices}.
1203 @node Voices and vocals
1204 @subsection Voices and vocals
1206 Vocal music presents a special difficulty: we need to combine two
1207 expressions -- notes and lyrics.
1209 @funindex \new Lyrics
1213 @cindex Lyrics context, creating
1214 @cindex lyrics, linking to voice
1216 You have already seen the @code{\addlyrics@{@}} command, which
1217 handles simple scores well. However, this technique is
1218 quite limited. For more complex music, you must introduce the
1219 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1221 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1222 name assigned to the Voice.
1224 @lilypond[quote,verbatim]
1226 \new Voice = "one" {
1230 c4 b8. a16 | g4. f8 | e4 d | c2 |
1233 \new Lyrics \lyricsto "one" {
1234 No more let | sins and | sor -- rows | grow. |
1239 Note that the lyrics must be linked to a @code{Voice} context,
1240 @emph{not} a @code{Staff} context. This is a case where it is
1241 necessary to create @code{Staff} and @code{Voice} contexts
1244 @cindex lyrics and beaming
1245 @cindex beaming and lyrics
1246 @funindex \autoBeamOff
1247 @funindex autoBeamOff
1249 The automatic beaming which LilyPond uses by default works well
1250 for instrumental music, but not so well for music with lyrics,
1251 where beaming is either not required at all or is used to indicate
1252 melismata in the lyrics. In the example above we use the command
1253 @code{\autoBeamOff} to turn off the automatic beaming.
1255 @funindex \new ChoirStaff
1256 @funindex ChoirStaff
1257 @funindex \lyricmode
1259 @cindex vocal score structure
1262 Let us reuse the earlier example from Judas Maccabæus to
1263 illustrate this more flexible technique. We first recast
1264 it to use variables so the music and lyrics can be separated
1265 from the staff structure. We also introduce a ChoirStaff
1266 bracket. The lyrics themselves must be introduced with
1267 @code{\lyricmode} to ensure they are interpreted as lyrics
1270 @lilypond[quote,verbatim]
1271 global = { \key f \major \time 6/8 \partial 8 }
1273 SopOneMusic = \relative c'' {
1274 c8 | c8([ bes)] a a([ g)] f | f'4. b, | c4.~ c4
1276 SopOneLyrics = \lyricmode {
1277 Let | flee -- cy flocks the | hills a -- dorn, __
1279 SopTwoMusic = \relative c' {
1280 r8 | r4. r4 c8 | a'8([ g)] f f([ e)] d | e8([ d)] c bes'
1282 SopTwoLyrics = \lyricmode {
1283 Let | flee -- cy flocks the | hills a -- dorn,
1289 \new Voice = "SopOne" {
1293 \new Lyrics \lyricsto "SopOne" {
1298 \new Voice = "SopTwo" {
1302 \new Lyrics \lyricsto "SopTwo" {
1310 This is the basic structure of all vocal scores. More staves may be
1311 added as required, more voices may be added to the staves, more verses
1312 may be added to the lyrics, and the variables containing the music can
1313 easily be placed in separate files should they become too long.
1315 @cindex hymn structure
1316 @cindex SATB structure
1317 @cindex vocal scores with multiple verses
1318 @cindex multiple vocal verses
1319 @cindex verses, multiple vocal
1321 Here is an example of the first line of a hymn with four
1322 verses, set for SATB. In this case the words for all four
1323 parts are the same. Note how we use variables to separate the
1324 music notation and words from the staff structure. See too
1325 how a variable, which we have chosen to call @q{keyTime}, is used
1326 to hold several commands for use within the two staves. In other
1327 examples this is often called @q{global}.
1329 @lilypond[quote,verbatim]
1330 keyTime = { \key c \major \time 4/4 \partial 4 }
1332 SopMusic = \relative c' { c4 | e4. e8 g4 g | a4 a g }
1333 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f4 f e }
1334 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1335 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1338 \lyricmode { E -- | ter -- nal fa -- ther, | strong to save, }
1340 \lyricmode { O | Christ, whose voice the | wa -- ters heard, }
1342 \lyricmode { O | Ho -- ly Spi -- rit, | who didst brood }
1344 \lyricmode { O | Tri -- ni -- ty of | love and pow'r }
1350 \new Voice = "Sop" { \voiceOne \keyTime \SopMusic }
1351 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1352 \new Lyrics \lyricsto "Sop" { \VerseOne }
1353 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1354 \new Lyrics \lyricsto "Sop" { \VerseThree }
1355 \new Lyrics \lyricsto "Sop" { \VerseFour }
1359 \new Voice = "Tenor" { \voiceOne \keyTime \TenorMusic }
1360 \new Voice = "Bass" { \voiceTwo \BassMusic }
1368 Notation Reference: @ruser{Vocal music}.
1371 @node Contexts and engravers
1372 @section Contexts and engravers
1374 Contexts and engravers have been mentioned informally
1375 in earlier sections; we now must look at
1376 these concepts in more detail, as they are important
1377 in the fine-tuning of LilyPond output.
1381 * Contexts explained::
1382 * Creating contexts::
1383 * Engravers explained::
1384 * Modifying context properties::
1385 * Adding and removing engravers::
1388 @node Contexts explained
1389 @subsection Contexts explained
1391 @cindex contexts explained
1393 When music is printed, many notational elements which do not
1394 appear explicitly in the input file must be added to the
1395 output. For example, compare the input and output of the
1398 @lilypond[quote,verbatim,relative=2]
1399 cis4 cis2. | a4 a2. |
1402 The input is rather sparse, but in the output, bar lines,
1403 accidentals, clef, and time signature have been added. When
1404 LilyPond @emph{interprets} the input the musical information
1405 is parsed from left to right, similar to the way a performer
1406 reads the score. While reading the input, the program remembers
1407 where measure boundaries are, and which pitches require explicit
1408 accidentals. This information must be held on several levels.
1409 For example, an accidental affects only a single staff, while
1410 a bar line must be synchronized across the entire score.
1412 Within LilyPond, these rules and bits of information are grouped in
1413 @emph{Contexts}. We have already introduced the @code{Voice} context.
1414 Others are the @code{Staff} and @code{Score} contexts. Contexts are
1415 hierarchical to reflect the hierarchical nature of a musical score.
1416 For example: a @code{Staff} context can contain many @code{Voice}
1417 contexts, and a @code{Score} context can contain many @code{Staff}
1421 @sourceimage{context-example,5cm,,}
1424 Each context has the responsibility for enforcing some notation rules,
1425 creating some notation objects and maintaining the associated
1426 properties. For example, the @code{Voice} context may introduce an
1427 accidental and then the @code{Staff} context maintains the rule to
1428 show or suppress the accidental for the remainder of the measure.
1430 As another example, the synchronization of bar lines is, by default,
1431 handled in the @code{Score} context.
1432 However, in some music we may not want the bar lines to be
1433 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1434 In such cases, we must modify the default settings of the
1435 @code{Score} and @code{Staff} contexts.
1437 For very simple scores, contexts are created implicitly, and you need
1438 not be aware of them. For larger pieces, such as anything with more
1439 than one staff, they must be
1440 created explicitly to make sure that you get as many staves as you
1441 need, and that they are in the correct order. For typesetting pieces
1442 with specialized notation, it is usual to modify existing, or
1443 even to define totally new, contexts.
1445 In addition to the @code{Score,} @code{Staff} and
1446 @code{Voice} contexts there are contexts which fit between
1447 the score and staff levels to control staff groups, such as the
1448 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1449 are also alternative staff and voice contexts, and contexts for
1450 lyrics, percussion, fret boards, figured bass, etc.
1452 The names of all context types are formed from one or more
1453 words, each word being capitalized and joined immediately to the
1454 preceding word with no hyphen or underscore, e.g.,
1455 @code{GregorianTranscriptionStaff}.
1459 Notation Reference: @ruser{Contexts explained}.
1462 @node Creating contexts
1463 @subsection Creating contexts
1467 @cindex new contexts
1468 @cindex creating contexts
1469 @cindex contexts, creating
1471 In an input file a score block, introduced with a @code{\score}
1472 command, contains a single music expression and an associated
1473 output definition (either a @code{\layout} or a @code{\midi} block).
1474 The @code{Score} context is usually left to be created automatically
1475 when the interpretation of that music expression starts.
1477 For scores with only one voice and one staff, the @code{Voice} and
1478 @code{Staff} contexts may also be left to be created automatically,
1479 but for more complex scores it is necessary to create them by hand.
1480 The simplest command that does this is @code{\new}. It is prepended
1481 to a music expression, for example
1484 \new @var{type} @var{music-expression}
1488 where @var{type} is a context name (like @code{Staff} or
1489 @code{Voice}). This command creates a new context, and starts
1490 interpreting the @var{music-expression} within that context.
1492 @warning{@bs{}@code{new Score} should not be used as the essential
1493 top-level @code{Score} context is created automatically when the music
1494 expression within the @bs{}@code{score} block is interpreted. Score-wide
1495 default values of context properties can be changed within the
1496 @bs{}@code{layout} block. See @ref{Modifying context properties}}
1498 You have seen many practical examples which created new
1499 @code{Staff} and @code{Voice} contexts in earlier sections, but
1500 to remind you how these commands are used in practice, here's an
1501 annotated real-music example:
1503 @lilypond[quote,verbatim,ragged-right]
1504 \score { % start of single compound music expression
1505 << % start of simultaneous staves section
1507 \new Staff { % create RH staff
1510 \new Voice { % create voice for RH notes
1511 \relative c'' { % start of RH notes
1517 \new Staff << % create LH staff; needs two simultaneous voices
1520 \new Voice { % create LH voice one
1522 \relative g { % start of LH voice one notes
1523 g8 <bes d> ees, <g c> |
1524 g8 <bes d> ees, <g c> |
1525 } % end of LH voice one notes
1526 } % end of LH voice one
1527 \new Voice { % create LH voice two
1529 \relative g { % start of LH voice two notes
1532 } % end of LH voice two notes
1533 } % end of LH voice two
1534 >> % end of LH staff
1535 >> % end of simultaneous staves section
1536 } % end of single compound music expression
1539 (Note how all the statements which open a block with either a
1540 curly bracket, @code{@{}, or double angle brackets, @code{<<},
1541 are indented by two further spaces, and the corresponding
1542 closing bracket is indented by exactly the same amount. While
1543 this is not required, following this practice will greatly
1544 reduce the number of @q{unmatched bracket} errors, and is
1545 strongly recommended. It enables the structure of the music to
1546 be seen at a glance, and any unmatched brackets will be obvious.
1547 Note too how the LH staff is created using double angle brackets
1548 because it requires two voices for its music, whereas the RH staff
1549 is created with a single music expression surrounded by curly
1550 brackets because it requires only one voice.)
1552 @cindex contexts, naming
1553 @cindex naming contexts
1555 The @code{\new} command may also give an identifying name to the
1556 context to distinguish it from other contexts of the same type,
1559 \new @var{type} = @var{id} @var{music-expression}
1562 Note the distinction between the name of the context type,
1563 @code{Staff}, @code{Voice}, etc, and the identifying name of a
1564 particular instance of that type, which can be any sequence of letters
1565 invented by the user. Digits and spaces can also be used in the
1566 identifying name, but then it has to be placed in quotes,
1567 i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
1568 The identifying name is used to
1569 refer back to that particular instance of a context. We saw this in
1570 use in the section on lyrics, see @ref{Voices and vocals}.
1574 Notation Reference: @ruser{Creating contexts}.
1577 @node Engravers explained
1578 @subsection Engravers explained
1582 Every mark on the printed output of a score produced by LilyPond
1583 is produced by an @code{Engraver}. Thus there is an engraver
1584 to print staves, one to print note heads, one for stems, one for
1585 beams, etc, etc. In total there are over 120 such engravers!
1586 Fortunately, for most scores it is not necessary to know about
1587 more than a few, and for simple scores you do not need to know
1590 Engravers live and operate in Contexts. Engravers such as the
1591 @code{Metronome_mark_engraver}, whose action and output apply to the
1592 score as a whole, operate in the highest level context -- the
1593 @code{Score} context.
1595 The @code{Clef_engraver} and @code{Key_engraver} are to be
1596 found in every @code{Staff} Context, as different staves may require
1597 different clefs and keys.
1599 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1600 in every @code{Voice} context, the lowest level context of all.
1602 Each engraver processes the particular objects associated
1603 with its function, and maintains the properties that relate
1604 to that function. These properties, like the properties
1605 associated with contexts, may be modified to change the
1606 operation of the engraver or the appearance of those elements
1607 in the printed score.
1609 Engravers all have compound names formed from words which
1610 describe their function. Just the first word is capitalized,
1611 and the remainder are joined to it with underscores. Thus
1612 the @code{Staff_symbol_engraver} is responsible for creating the
1613 lines of the staff, the @code{Clef_engraver} determines and sets
1614 the pitch reference point on the staff by drawing a clef symbol.
1616 Here are some of the most common engravers together with their
1617 function. You will see it is usually easy to guess the function
1618 from the name, or vice versa.
1620 @multitable @columnfractions .3 .7
1623 @item Accidental_engraver
1624 @tab Makes accidentals, cautionary and suggested accidentals
1629 @item Completion_heads_engraver
1630 @tab Splits notes which cross bar lines
1631 @c The old Dynamic_engraver is deprecated. -jm
1632 @item New_dynamic_engraver
1633 @tab Creates hairpins and dynamic texts
1634 @item Forbid_line_break_engraver
1635 @tab Prevents line breaks if a musical element is still active
1637 @tab Creates the key signature
1638 @item Metronome_mark_engraver
1639 @tab Engraves metronome marking
1640 @item Note_heads_engraver
1641 @tab Engraves note heads
1644 @item Staff_symbol_engraver
1645 @tab Engraves the five (by default) lines of the staff
1647 @tab Creates stems and single-stem tremolos
1648 @item Time_signature_engraver
1649 @tab Creates time signatures
1654 We shall see later how the output of LilyPond can be changed
1655 by modifying the action of Engravers.
1659 Internals reference: @rinternals{Engravers and Performers}.
1662 @node Modifying context properties
1663 @subsection Modifying context properties
1665 @cindex context properties
1666 @cindex context properties, modifying
1667 @cindex modifying context properties
1673 Contexts are responsible for holding the values of a number of
1674 context @emph{properties}. Many of them can be changed to
1675 influence the interpretation of the input and so change the
1676 appearance of the output. They are changed by the
1677 @code{\set} command. This takes the form
1680 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1683 Where the @emph{ContextName} is usually @code{Score},
1684 @code{Staff} or @code{Voice}. It may be omitted,
1685 in which case the current context (typically @code{Voice}) is assumed.
1687 The names of context properties consist of words joined
1688 together with no hyphens or underscores, all except the
1689 first having a capital letter. Here are a few examples
1690 of some commonly used ones. There are many more.
1692 @c attempt to force this onto a new page
1694 @multitable @columnfractions .25 .15 .45 .15
1695 @headitem propertyName
1701 @tab If true, set extra natural signs before accidentals
1702 @tab @code{#t}, @code{#f}
1703 @item currentBarNumber
1705 @tab Set the current bar number
1709 @tab If true, print slurs both above and below notes
1710 @tab @code{#t}, @code{#f}
1711 @item instrumentName
1713 @tab Set the name to be placed at the start of the staff
1714 @tab @code{"Cello I"}
1717 @tab Increase or decrease the font size
1721 @tab Set the text to print before the start of a verse
1726 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1727 an Integer is a positive whole number, a Real is a positive
1728 or negative decimal number, and text is enclosed in double
1729 apostrophes. Note the occurrence of hash signs,
1730 (@code{#}), in two different places -- as part of the Boolean
1731 value before the @code{t} or @code{f}, and before @emph{value}
1732 in the @code{\set} statement. So when a Boolean is being
1733 entered you need to code two hash signs, e.g., @code{##t}.
1735 @cindex properties operating in contexts
1736 @cindex setting properties within contexts
1738 Before we can set any of these properties we need to know
1739 in which context they operate. Sometimes this is obvious,
1740 but occasionally it can be tricky. If the wrong context
1741 is specified, no error message is produced, but the expected
1742 action will not take place. For example, the
1743 @code{instrumentName} clearly lives in the @code{Staff} context, since
1744 it is the staff that is to be named.
1745 In this example the first staff is labeled, but not the second,
1746 because we omitted the context name.
1748 @lilypond[quote,verbatim,ragged-right]
1750 \new Staff \relative c'' {
1751 \set Staff.instrumentName = #"Soprano"
1754 \new Staff \relative c' {
1755 \set instrumentName = #"Alto" % Wrong!
1761 Remember the default context name is @code{Voice}, so the second
1762 @code{\set} command set the property @code{instrumentName} in the
1763 @code{Voice} context to @qq{Alto}, but as LilyPond does not look
1764 for any such property in the @code{Voice} context, no
1765 further action took place. This is not an error, and no error
1766 message is logged in the log file.
1768 Similarly, if the property name is mis-spelt no error message is
1769 produced, and clearly the expected action cannot be performed. In
1770 fact, you can set any (fictitious) @q{property} using any name you
1771 like in any context that exists by using the @code{\set} command. But
1772 if the name is not known to LilyPond it will not cause any action to
1773 be taken. Some text editors with special support for LilyPond input
1774 files document property names with bullets when you hover them with
1775 the mouse, like JEdit with LilyPondTool, or highlight unknown property
1776 names differently, like ConTEXT. If you do not use an editor with
1777 such features, it is recommended to check the property name in the
1778 Internals Reference: see @rinternals{Tunable context properties}, or
1779 @rinternals{Contexts}.
1781 The @code{instrumentName} property will take effect only
1782 if it is set in the @code{Staff} context, but
1783 some properties can be set in more than one context.
1784 For example, the property @code{extraNatural} is by
1785 default set to ##t (true) for all staves.
1786 If it is set to ##f (false) in one particular @code{Staff}
1787 context it applies just to the accidentals on that staff.
1788 If it is set to false in the @code{Score} context
1789 it applies to all staves.
1791 So this turns off extra naturals in one staff:
1793 @lilypond[quote,verbatim,ragged-right]
1795 \new Staff \relative c'' {
1798 \new Staff \relative c'' {
1799 \set Staff.extraNatural = ##f
1806 and this turns them off in all staves:
1808 @lilypond[quote,verbatim,ragged-right]
1810 \new Staff \relative c'' {
1813 \new Staff \relative c'' {
1814 \set Score.extraNatural = ##f
1820 As another example, if @code{clefOctavation} is set in
1821 the @code{Score} context this immediately changes the value
1822 of the octavation in all current staves and sets a new default
1823 value which will be applied to all staves.
1825 The opposite command, @code{\unset}, effectively removes the
1826 property from the context, which causes most properties to
1827 revert to their default value. Usually @code{\unset} is not
1828 required as a new @code{\set} command will achieve what is
1831 The @code{\set} and @code{\unset} commands can appear anywhere
1832 in the input file and will take effect from the time they are
1833 encountered until the end of the score or until the property is
1834 @code{\set} or @code{\unset} again. Let's try changing the
1835 font size, which affects the size of the note heads (among
1836 other things) several times. The change is from the default
1837 value, not the most recently set value.
1839 @lilypond[quote,verbatim,ragged-right,relative=1]
1841 % make note heads smaller
1844 % make note heads larger
1845 \set fontSize = #2.5
1847 % return to default size
1852 We have now seen how to set the values of several different types of
1853 property. Note that integers and numbers are always preceded by a
1854 hash sign, @code{#}, while a true or false value is specified by
1855 @code{##t} and @code{##f}, with two hash signs. A text property
1856 should be enclosed in double quotation signs, as above, although we
1857 shall see later that text can actually be specified in a much more
1858 general way by using the very powerful @code{\markup} command.
1860 @subsubheading Setting context properties with @code{\with}
1864 @cindex context properties, setting with \with
1866 The default value of context properties may be set at the time the
1867 context is created. Sometimes this is a clearer way of setting a
1868 property value if it is to remain fixed for the duration of
1869 the context. When a context is created with a @code{\new}
1870 command it may be followed immediately by a @code{\with @{ .. @}}
1871 block in which the default property values are set. For example,
1872 if we wish to suppress the printing of extra naturals for the
1873 duration of a staff we would write:
1876 \new Staff \with @{ extraNatural = ##f @}
1882 @lilypond[quote,verbatim,ragged-right]
1886 gisis4 gis aeses aes
1889 \new Staff \with { extraNatural = ##f } {
1891 gisis4 gis aeses aes
1897 Properties set in this way may still be changed dynamically using
1898 @code{\set} and returned to the default value set in the
1899 @code{\with} block with @code{\unset}.
1901 @cindex fontSize, default and setting
1903 So if the @code{fontSize} property is set in a @code{\with} clause
1904 it sets the default value of the font size. If it is later changed
1905 with @code{\set}, this new default value may be restored with the
1906 @code{\unset fontSize} command.
1908 @subsubheading Setting context properties with @code{\context}
1910 @cindex context properties, setting with \context
1914 The values of context properties may be set in @emph{all} contexts
1915 of a particular type, such as all @code{Staff} contexts, with a single
1916 command. The context type is identified by using its
1917 type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
1918 The statement which sets the property value is the same as that in a
1919 @code{\with} block, introduced above. It is placed in a
1920 @code{\context} block within a @code{\layout} block. Each
1921 @code{\context} block will affect all contexts of the type specified
1922 throughout the @code{\score} or @code{\book} block in which the
1923 @code{\layout} block appears. Here is a example to show the format:
1925 @lilypond[verbatim,quote]
1941 If the property override is to be applied to all staves
1944 @lilypond[quote,verbatim]
1949 gisis4 gis aeses aes
1954 gisis4 gis aeses aes
1960 \Score extraNatural = ##f
1967 Context properties set in this way may be overridden for particular
1968 instances of contexts by statements in a @code{\with} block, and by
1969 @code{\set} commands embedded in music statements.
1974 @ruser{Changing context default settings}.
1975 @ruser{The set command}.
1977 Internals Reference:
1978 @rinternals{Contexts},
1979 @rinternals{Tunable context properties}.
1982 @node Adding and removing engravers
1983 @subsection Adding and removing engravers
1985 @cindex engravers, adding
1986 @cindex adding engravers
1987 @cindex engravers, removing
1988 @cindex removing engravers
1995 We have seen that contexts each contain several engravers, each
1996 of which is responsible for producing a particular part of the
1997 output, like bar lines, staves, note heads, stems, etc. If an
1998 engraver is removed from a context, it can no longer produce its
1999 output. This is a crude way of modifying the output, but it
2000 can sometimes be useful.
2002 @subsubheading Changing a single context
2004 To remove an engraver from a single context we use the
2005 @code{\with} command placed immediately after the context creation
2006 command, as in the previous section.
2008 As an illustration, let's repeat an example from the previous section
2009 with the staff lines removed. Remember that the staff lines are
2010 produced by the @code{Staff_symbol_engraver}.
2012 @lilypond[quote,verbatim,ragged-right]
2014 \remove "Staff_symbol_engraver"
2018 \set fontSize = #-4 % make note heads smaller
2020 \set fontSize = #2.5 % make note heads larger
2022 \unset fontSize % return to default size
2027 @cindex ambitus engraver
2029 Engravers can also be added to individual contexts.
2030 The command to do this is
2032 @code{\consists @var{Engraver_name}},
2035 placed inside a @code{\with} block. Some vocal scores have an ambitus
2036 placed at the beginning of a staff to indicate the range of notes in
2037 that staff -- see @rglos{ambitus}. The ambitus is produced by the
2038 @code{Ambitus_engraver}, which is not normally included in any
2039 context. If we add it to the @code{Voice} context, it calculates the
2040 range from that voice only:
2042 @lilypond[quote,verbatim,ragged-right]
2045 \consists "Ambitus_engraver"
2062 but if we add the ambitus engraver to the
2063 @code{Staff} context, it calculates the range from all
2064 the notes in all the voices on that staff:
2066 @lilypond[quote,verbatim,ragged-right]
2068 \consists "Ambitus_engraver"
2086 @subsubheading Changing all contexts of the same type
2091 The examples above show how to remove or add engravers to
2092 individual contexts. It is also possible to remove or add
2093 engravers to every context of a specific type by placing the
2094 commands in the appropriate context in a @code{\layout}
2095 block. For example, if we wanted to show an ambitus for every
2096 staff in a four-staff score, we could write
2098 @lilypond[quote,verbatim,ragged-right]
2127 \consists "Ambitus_engraver"
2134 The values of context properties may also be set
2135 for all contexts of a particular type by including the
2136 @code{\set} command in a @code{\context} block in the
2140 Notation Reference: @ruser{Modifying context plug-ins},
2141 @ruser{Changing context default settings}.
2144 The @code{Stem_engraver} and @code{Beam_engraver} attach their
2145 objects to note heads. If the @code{Note_heads_engraver} is removed
2146 no note heads are produced and therefore no stems or beams are created
2150 @node Extending the templates
2151 @section Extending the templates
2153 You've read the tutorial, you know how to write music, you
2154 understand the fundamental concepts. But how can you
2155 get the staves that you want? Well, you can find lots of
2156 templates (see @ref{Templates}) which may give you a start.
2157 But what if you want something that isn't covered there? Read on.
2160 * Soprano and cello::
2161 * Four-part SATB vocal score::
2162 * Building a score from scratch::
2163 * Saving typing with variables and functions::
2164 * Scores and parts::
2167 @node Soprano and cello
2168 @subsection Soprano and cello
2170 @cindex template, modifying
2171 @cindex modifying templates
2173 Start off with the template that seems closest to what you want to
2174 end up with. Let's say that you want to write something for
2175 soprano and cello. In this case, we would start with the
2176 @q{Notes and lyrics} template (for the soprano part).
2179 \version @w{"@version{}"}
2181 melody = \relative c' @{
2188 text = \lyricmode @{
2194 \new Voice = "one" @{
2198 \new Lyrics \lyricsto "one" \text
2205 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2208 \version @w{"@version{}"}
2210 melody = \relative c' @{
2224 We don't need two @code{\version} commands. We'll need the
2225 @code{melody} section. We don't want two @code{\score} sections
2226 -- if we had two @code{\score}s, we'd get the two parts separately.
2227 We want them together, as a duet. Within the @code{\score}
2228 section, we don't need two @code{\layout} or @code{\midi}.
2230 If we simply cut and paste the @code{melody} section, we would
2231 end up with two @code{melody} definitions. This would not generate
2232 an error, but the second one would be used for both melodies.
2233 So let's rename them to make them distinct. We'll call the
2234 section for the soprano @code{sopranoMusic} and the section for
2235 the cello @code{celloMusic}. While we're doing this, let's rename
2236 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2237 instances of all these names -- both the initial definition (the
2238 @code{melody = \relative c' @{ } part) and the name's use (in the
2239 @code{\score} section).
2241 While we're doing this, let's change the cello part's staff --
2242 celli normally use bass clef. We'll also give the cello some
2246 \version @w{"@version{}"}
2248 sopranoMusic = \relative c' @{
2255 sopranoLyrics = \lyricmode @{
2259 celloMusic = \relative c @{
2268 \new Voice = "one" @{
2272 \new Lyrics \lyricsto "one" \sopranoLyrics
2279 This is looking promising, but the cello part won't appear in the
2280 score -- we haven't used it in the @code{\score} section. If we
2281 want the cello part to appear under the soprano part, we need to add
2284 \new Staff \celloMusic
2288 underneath the soprano stuff. We also need to add @code{<<} and
2289 @code{>>} around the music -- that tells LilyPond that there's
2290 more than one thing (in this case, two @code{Staves}) happening
2291 at once. The @code{\score} looks like this now:
2293 @c Indentation in this example is deliberately poor
2298 \new Voice = "one" @{
2302 \new Lyrics \lyricsto "one" \sopranoLyrics
2304 \new Staff \celloMusic
2312 This looks a bit messy; the indentation is messed up now. That is
2313 easily fixed. Here's the complete soprano and cello template.
2315 @lilypond[quote,verbatim,ragged-right,addversion]
2316 sopranoMusic = \relative c' {
2323 sopranoLyrics = \lyricmode {
2327 celloMusic = \relative c {
2337 \new Voice = "one" {
2341 \new Lyrics \lyricsto "one" \sopranoLyrics
2343 \new Staff \celloMusic
2352 The starting templates can be found in the @q{Templates} appendix,
2353 see @ref{Single staff templates}.
2356 @node Four-part SATB vocal score
2357 @subsection Four-part SATB vocal score
2359 @cindex template, SATB
2360 @cindex SATB template
2362 Most vocal scores of music written for four-part mixed choir
2363 with orchestral accompaniment such as Mendelssohn's Elijah or
2364 Handel's Messiah have the choral music and words on four
2365 staves, one for each of SATB, with a piano reduction of the
2366 orchestral accompaniment underneath. Here's an example
2367 from Handel's Messiah:
2369 @c The following should appear as music without code
2370 @lilypond[quote,ragged-right]
2371 global = { \key d \major \time 4/4 }
2373 sopranoMusic = \relative c'' {
2375 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2377 sopranoWords = \lyricmode {
2378 Wor -- thy | is the lamb | that was slain |
2381 altoMusic = \relative a' {
2383 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
2385 altoWords = \sopranoWords
2387 tenorMusic = \relative c' {
2389 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2391 tenorWords = \sopranoWords
2393 bassMusic = \relative c' {
2395 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2397 bassWords = \sopranoWords
2399 upper = \relative a' {
2402 r4 <a d fis>2 <a e' a>4 |
2403 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2404 <g cis g'>4 <a d fis> <a cis e>2 |
2407 lower = \relative c, {
2410 <d d'>4 <d d'>2 <cis cis'>4 |
2411 <b b'>4. <b' b'>8 <fis fis'>2 |
2412 <e e'>4 <d d'> <a' a'>2 |
2416 << % combine ChoirStaff and PianoStaff in parallel
2418 \new Staff = "sopranos" <<
2419 \set Staff.instrumentName = #"Soprano"
2420 \new Voice = "sopranos" {
2425 \new Lyrics \lyricsto "sopranos" {
2428 \new Staff = "altos" <<
2429 \set Staff.instrumentName = #"Alto"
2430 \new Voice = "altos" {
2435 \new Lyrics \lyricsto "altos" { \altoWords }
2436 \new Staff = "tenors" <<
2437 \set Staff.instrumentName = #"Tenor"
2438 \new Voice = "tenors" {
2443 \new Lyrics \lyricsto "tenors" { \tenorWords }
2444 \new Staff = "basses" <<
2445 \set Staff.instrumentName = #"Bass"
2446 \new Voice = "basses" {
2451 \new Lyrics \lyricsto "basses" {
2456 \set PianoStaff.instrumentName = #"Piano"
2457 \new Staff = "upper" \upper
2458 \new Staff = "lower" \lower
2464 None of the templates provides this layout exactly. The nearest is
2465 @ref{SATB vocal score and automatic piano reduction} -- but we need
2466 to change the layout and add a piano
2467 accompaniment which is not derived automatically from the vocal parts.
2468 The variables holding the music and words for the vocal parts are
2469 fine, but we shall need to add variables for the piano reduction.
2471 The order in which the contexts appear in the ChoirStaff of the
2472 template do not correspond with the order in the vocal score shown
2473 above. We need to rearrange them so there are four staves with the
2474 words written directly underneath the notes for each part. All the
2475 voices should be @code{\voiceOne}, which is the default, so the
2476 @code{\voiceXXX} commands should be removed. We also need to specify
2477 the tenor clef for the tenors. The way in which lyrics are specified
2478 in the template has not yet been encountered so we need to use the
2479 method with which we are familiar. We should also add the names of
2482 Doing this gives for our ChoirStaff:
2486 \new Staff = "sopranos" <<
2487 \set Staff.instrumentName = #"Soprano"
2488 \new Voice = "sopranos" @{
2493 \new Lyrics \lyricsto "sopranos" @{
2496 \new Staff = "altos" <<
2497 \set Staff.instrumentName = #"Alto"
2498 \new Voice = "altos" @{
2503 \new Lyrics \lyricsto "altos" @{
2506 \new Staff = "tenors" <<
2507 \set Staff.instrumentName = #"Tenor"
2508 \new Voice = "tenors" @{
2513 \new Lyrics \lyricsto "tenors" @{
2516 \new Staff = "basses" <<
2517 \set Staff.instrumentName = #"Bass"
2518 \new Voice = "basses" @{
2523 \new Lyrics \lyricsto "basses" @{
2529 Next we must work out the piano part. This is
2530 easy - we just pull out the piano part from the
2531 @q{Solo piano} template:
2535 \set PianoStaff.instrumentName = #"Piano "
2536 \new Staff = "upper" \upper
2537 \new Staff = "lower" \lower
2541 and add the variable definitions for @code{upper}
2544 The ChoirStaff and PianoStaff must be combined
2545 using angle brackets as we want them to be
2546 stacked one above the other:
2549 << % combine ChoirStaff and PianoStaff one above the other
2551 \new Staff = "sopranos" <<
2552 \new Voice = "sopranos" @{
2557 \new Lyrics \lyricsto "sopranos" @{
2560 \new Staff = "altos" <<
2561 \new Voice = "altos" @{
2566 \new Lyrics \lyricsto "altos" @{
2569 \new Staff = "tenors" <<
2570 \clef "G_8" % tenor clef
2571 \new Voice = "tenors" @{
2576 \new Lyrics \lyricsto "tenors" @{
2579 \new Staff = "basses" <<
2581 \new Voice = "basses" @{
2586 \new Lyrics \lyricsto "basses" @{
2592 \set PianoStaff.instrumentName = #"Piano"
2593 \new Staff = "upper" \upper
2594 \new Staff = "lower" \lower
2599 Combining all these together and adding the music
2600 for the three bars of the example above gives:
2602 @lilypond[quote,verbatim,ragged-right,addversion]
2603 global = { \key d \major \time 4/4 }
2604 sopranoMusic = \relative c'' {
2606 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2608 sopranoWords = \lyricmode {
2609 Wor -- thy | is the lamb | that was slain |
2611 altoMusic = \relative a' {
2613 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2615 altoWords = \sopranoWords
2616 tenorMusic = \relative c' {
2618 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2620 tenorWords = \sopranoWords
2621 bassMusic = \relative c' {
2623 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2625 bassWords = \sopranoWords
2626 upper = \relative a' {
2629 r4 <a d fis>2 <a e' a>4 |
2630 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2631 <g cis g'>4 <a d fis> <a cis e>2 |
2633 lower = \relative c, {
2636 <d d'>4 <d d'>2 <cis cis'>4 |
2637 <b b'>4. <b' b'>8 <fis fis'>2 |
2638 <e e'>4 <d d'> <a' a'>2 |
2642 << % combine ChoirStaff and PianoStaff in parallel
2644 \new Staff = "sopranos" <<
2645 \set Staff.instrumentName = #"Soprano"
2646 \new Voice = "sopranos" {
2651 \new Lyrics \lyricsto "sopranos" {
2654 \new Staff = "altos" <<
2655 \set Staff.instrumentName = #"Alto"
2656 \new Voice = "altos" {
2661 \new Lyrics \lyricsto "altos" {
2664 \new Staff = "tenors" <<
2665 \set Staff.instrumentName = #"Tenor"
2666 \new Voice = "tenors" {
2671 \new Lyrics \lyricsto "tenors" {
2674 \new Staff = "basses" <<
2675 \set Staff.instrumentName = #"Bass"
2676 \new Voice = "basses" {
2681 \new Lyrics \lyricsto "basses" {
2687 \set PianoStaff.instrumentName = #"Piano "
2688 \new Staff = "upper" \upper
2689 \new Staff = "lower" \lower
2696 @node Building a score from scratch
2697 @subsection Building a score from scratch
2699 @cindex template, writing your own
2700 @cindex example of writing a score
2701 @cindex writing a score, example
2702 @cindex score, example of writing
2704 After gaining some facility with writing LilyPond code, you
2705 may find that it is easier to build a score from scratch
2706 rather than modifying one of the templates. You can also
2707 develop your own style this way to suit the sort of music you
2708 like. Let's see how to put together the score for an organ
2709 prelude as an example.
2711 We begin with a header section. Here go the title, name
2712 of composer, etc, then come any variable definitions, and
2713 finally the score block. Let's start with these in outline
2714 and fill in the details later.
2716 We'll use the first two bars of Bach's prelude
2717 based on @emph{Jesu, meine Freude} which is written for two
2718 manuals and pedal organ. You can see these two bars of music
2719 at the bottom of this section. The top manual part has two voices,
2720 the lower and pedal organ one each. So we need four
2721 music definitions and one to define the time signature
2725 \version @w{"@version{}"}
2727 title = "Jesu, meine Freude"
2728 composer = "J S Bach"
2730 keyTime = @{ \key c \minor \time 4/4 @}
2731 ManualOneVoiceOneMusic = @{ s1 @}
2732 ManualOneVoiceTwoMusic = @{ s1 @}
2733 ManualTwoMusic = @{ s1 @}
2734 PedalOrganMusic = @{ s1 @}
2740 For now we've just used a spacer note, @code{s1},
2741 instead of the real music. We'll add that later.
2743 Next let's see what should go in the score block.
2744 We simply mirror the staff structure we want.
2745 Organ music is usually written on three staves,
2746 one for each manual and one for the pedals. The
2747 manual staves should be bracketed together, so we
2748 need to use a PianoStaff for them. The first
2749 manual part needs two voices and the second manual
2754 \new Staff = "ManualOne" <<
2756 \ManualOneVoiceOneMusic
2759 \ManualOneVoiceTwoMusic
2761 >> % end ManualOne Staff context
2762 \new Staff = "ManualTwo" <<
2766 >> % end ManualTwo Staff context
2767 >> % end PianoStaff context
2770 Next we need to add a staff for the pedal organ.
2771 This goes underneath the PianoStaff, but it must
2772 be simultaneous with it, so we need angle brackets
2773 around the two. Missing these out would generate
2774 an error in the log file. It's a common mistake
2775 which you'll make sooner or later! Try copying
2776 the final example at the end of this section,
2777 remove these angle brackets, and compile it to
2778 see what errors it generates.
2781 << % PianoStaff and Pedal Staff must be simultaneous
2783 \new Staff = "ManualOne" <<
2785 \ManualOneVoiceOneMusic
2788 \ManualOneVoiceTwoMusic
2790 >> % end ManualOne Staff context
2791 \new Staff = "ManualTwo" <<
2795 >> % end ManualTwo Staff context
2796 >> % end PianoStaff context
2797 \new Staff = "PedalOrgan" <<
2805 It is not necessary to use the simultaneous construct
2806 @code{<< .. >>} for the manual two staff and the pedal organ staff,
2807 since they contain only one music expression, but it does no harm,
2808 and always using angle brackets after @code{\new Staff} is a good
2809 habit to cultivate in case there are multiple voices. The opposite
2810 is true for Voices: these should habitually be followed by braces
2811 @code{@{ .. @}} in case your music is coded in several variables
2812 which need to run consecutively.
2814 Let's add this structure to the score block, and adjust the indenting.
2815 We also add the appropriate clefs, ensure stems, ties and slurs in
2816 each voice on the upper staff point to the right direction with
2817 @code{\voiceOne} and @code{\voiceTwo}, and enter the key and time
2818 signature to each staff using our predefined variable, @code{\keyTime}.
2822 << % PianoStaff and Pedal Staff must be simultaneous
2824 \new Staff = "ManualOne" <<
2825 \keyTime % set key and time signature
2829 \ManualOneVoiceOneMusic
2833 \ManualOneVoiceTwoMusic
2835 >> % end ManualOne Staff context
2836 \new Staff = "ManualTwo" <<
2842 >> % end ManualTwo Staff context
2843 >> % end PianoStaff context
2844 \new Staff = "PedalOrgan" <<
2850 >> % end PedalOrgan Staff
2852 @} % end Score context
2855 @cindex stretchability of staves
2856 @cindex staves, stretchability
2858 The above layout of the organ staves is almost perfect; however,
2859 there is a slight defect which is not visible by looking at just a
2860 single system: The distance of the pedal staff to the left hand staff
2861 should behave approximately the same as the right hand staff to the
2862 left hand staff. In particular, the stretchability of staves in a
2863 @code{PianoStaff} context is limited (so that the distance between
2864 the staves for the left and right hand can't become too large), and
2865 the pedal staff should behave similarly.
2867 @cindex sub-properties
2868 @cindex properties, sub-properties
2869 @cindex graphical objects
2870 @cindex objects, graphical
2873 Stretchability of staves can be controlled with the
2874 @code{staff-staff-spacing} property of the
2875 @code{VerticalAxisGroup} @q{graphical object} (commonly called
2876 @q{grob}s within the lilypond documentation) -- don't worry about
2877 the details right now; this is fully explained later. For the
2878 curious, have a look at @ruser{Overview of modifying properties}.
2879 In this case, we want to modify the @code{stretchability}
2880 sub-property only. Again, for the curious, you can find the
2881 default values for the staff-staff-spacing property
2882 in file @file{scm/define-grobs.scm} by looking up the definition
2883 of the @code{VerticalAxisGroup} grob. The value for
2884 @code{stretchability} is taken from the definition of the
2885 @code{PianoStaff} context (in file @file{ly/engraver-init.ly})
2886 so that the values are identical.
2890 << % PianoStaff and Pedal Staff must be simultaneous
2892 \new Staff = "ManualOne" <<
2893 \keyTime % set key and time signature
2897 \ManualOneVoiceOneMusic
2901 \ManualOneVoiceTwoMusic
2903 >> % end ManualOne Staff context
2904 \new Staff = "ManualTwo" \with @{
2905 \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
2912 >> % end ManualTwo Staff context
2913 >> % end PianoStaff context
2914 \new Staff = "PedalOrgan" <<
2920 >> % end PedalOrgan Staff
2922 @} % end Score context
2924 That completes the structure. Any three-staff organ music
2925 will have a similar structure, although the number of voices
2926 may vary. All that remains now
2927 is to add the music, and combine all the parts together.
2929 @lilypond[quote,verbatim,ragged-right,addversion]
2931 title = "Jesu, meine Freude"
2932 composer = "J S Bach"
2934 keyTime = { \key c \minor \time 4/4 }
2935 ManualOneVoiceOneMusic = \relative g' {
2939 ManualOneVoiceTwoMusic = \relative c' {
2940 ees16 d ees8~ ees16 f ees d c8 d~ d c~ |
2941 c8 c4 b8 c8. g16 c b c d |
2943 ManualTwoMusic = \relative c' {
2944 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2945 f16 ees f d g aes g f ees d ees8~ ees16 f ees d |
2947 PedalOrganMusic = \relative c {
2948 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2949 r16 g ees f g f g8 c,2 |
2953 << % PianoStaff and Pedal Staff must be simultaneous
2955 \new Staff = "ManualOne" <<
2956 \keyTime % set key and time signature
2960 \ManualOneVoiceOneMusic
2964 \ManualOneVoiceTwoMusic
2966 >> % end ManualOne Staff context
2967 \new Staff = "ManualTwo" \with {
2968 \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
2975 >> % end ManualTwo Staff context
2976 >> % end PianoStaff context
2977 \new Staff = "PedalOrgan" <<
2983 >> % end PedalOrgan Staff context
2985 } % end Score context
2992 @node Saving typing with variables and functions
2993 @subsection Saving typing with variables and functions
2998 By this point, you've seen this kind of thing:
3000 @lilypond[quote,verbatim,ragged-right]
3001 hornNotes = \relative c'' { c4 b dis c }
3010 You may even realize that this could be useful in minimalist music:
3012 @lilypond[quote,verbatim,ragged-right]
3013 fragmentA = \relative c'' { a4 a8. b16 }
3014 fragmentB = \relative c'' { a8. gis16 ees4 }
3016 violin = \new Staff {
3017 \fragmentA \fragmentA |
3018 \fragmentB \fragmentA |
3028 However, you can also use these variables (also known as
3029 macros, or user-defined commands) for tweaks:
3031 @c TODO Avoid padtext - not needed with skylining
3032 @lilypond[quote,verbatim,ragged-right]
3033 dolce = \markup { \italic \bold dolce }
3035 padText = { \once \override TextScript.padding = #5.0 }
3037 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
3040 violin = \relative c'' {
3042 c4._\dolce b8 a8 g a b |
3044 c4.^"hi there!" d8 e' f g d |
3045 c,4.\fthenp b8 c4 c-. |
3053 \layout { ragged-right = ##t }
3057 These variables are obviously useful for saving
3058 typing. But they're worth considering even if you
3059 only use them once -- they reduce complexity. Let's
3060 look at the previous example without any
3061 variables. It's a lot harder to read, especially
3065 violin = \relative c'' @{
3067 c4._\markup @{ \italic \bold dolce @} b8 a8 g a b |
3068 \once \override TextScript.padding = #5.0
3069 c4.^"hi there!" d8 e' f g d |
3071 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p
3078 @c TODO Replace the following with a better example -td
3079 @c Skylining handles this correctly without padText
3081 So far we've seen static substitution -- when LilyPond
3082 sees @code{\padText}, it replaces it with the stuff that
3083 we've defined it to be (ie the stuff to the right of
3086 LilyPond can handle non-static substitution, too (you
3087 can think of these as functions).
3089 @lilypond[quote,verbatim,ragged-right]
3091 #(define-music-function
3092 (parser location padding)
3095 \once \override TextScript.padding = #padding
3099 c4^"piu mosso" b a b |
3101 c4^"piu mosso" d e f |
3103 c4^"piu mosso" fis a g |
3107 Using variables is also a good way to reduce work if the
3108 LilyPond input syntax changes (see
3109 @rprogram{Updating files with convert-ly}). If
3110 you have a single definition (such as @code{\dolce}) for all your
3111 input files (see @ref{Style sheets}), then if the syntax changes, you
3112 only need to update your single @code{\dolce} definition,
3113 instead of making changes throughout every @file{.ly} file.
3116 @node Scores and parts
3117 @subsection Scores and parts
3119 In orchestral music, all notes are printed twice. Once in a part for
3120 the musicians, and once in a full score for the conductor. Variables can
3121 be used to avoid double work. The music is entered once, and stored in
3122 a variable. The contents of that variable is then used to generate
3123 both the part and the full score.
3125 It is convenient to define the notes in a special file. For example,
3126 suppose that the file @file{horn-music.ly} contains the following part
3127 of a horn/@/bassoon duo
3130 hornNotes = \relative c @{
3132 r4 f8 a | cis4 f | e4 d |
3137 Then, an individual part is made by putting the following in a file
3140 \include "horn-music.ly"
3143 instrument = "Horn in F"
3147 \transpose f c' \hornNotes
3154 \include "horn-music.ly"
3158 substitutes the contents of @file{horn-music.ly} at this position in
3159 the file, so @code{hornNotes} is defined afterwards. The command
3160 @code{\transpose f@tie{}c'} indicates that the argument, being
3161 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
3162 @code{f} is denoted by notated @code{c'}, which corresponds with the
3163 tuning of a normal French Horn in@tie{}F. The transposition can be seen
3164 in the following output
3166 @lilypond[quote,ragged-right]
3167 \transpose f c' \relative c {
3169 r4 f8 a | cis4 f | e4 d |
3173 In ensemble pieces, one of the voices often does not play for many
3174 measures. This is denoted by a special rest, the multi-measure
3175 rest. It is entered with a capital @code{R} followed by a duration
3176 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
3177 etc.). By multiplying the
3178 duration, longer rests can be constructed. For example, this rest
3179 takes 3@tie{}measures in 2/4 time
3185 When printing the part, multi-rests
3186 must be condensed. This is done by setting a run-time variable
3189 \set Score.skipBars = ##t
3193 This command sets the property @code{skipBars} in the
3194 @code{Score} context to true (@code{##t}). Prepending the rest and
3195 this option to the music above, leads to the following result
3197 @lilypond[quote,ragged-right]
3198 \transpose f c' \relative c {
3200 \set Score.skipBars = ##t
3202 r4 f8 a | cis4 f | e4 d |
3207 The score is made by combining all of the music together. Assuming
3208 that the other voice is in @code{bassoonNotes} in the file
3209 @file{bassoon-music.ly}, a score is made with
3212 \include "bassoon-music.ly"
3213 \include "horn-music.ly"
3216 \new Staff \hornNotes
3217 \new Staff \bassoonNotes
3224 @lilypond[quote,ragged-right]
3230 r4 f8 a | cis4 f | e4 d |
3235 r4 d,8 f | gis4 c | b4 bes |
3236 a8 e f4 | g4 d | gis4 f |