1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
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..
13 @node Fundamental concepts
14 @chapter Fundamental concepts
16 You've seen in the Tutorial how to produce beautifully printed
17 music from a simple text file. This section introduces the
18 concepts and techniques required to produce equally beautiful
19 but more complex scores.
22 * How LilyPond input files work::
23 * Voices contain music::
24 * Contexts and engravers::
25 * Extending the templates::
29 @node How LilyPond input files work
30 @section How LilyPond input files work
32 The LilyPond input format is quite free-form, giving experienced
33 users a lot of flexibility to structure their files however they
34 wish. But this flexibility can make things confusing for new
35 users. This section will explain some of this structure, but may
36 gloss over some details in favor of simplicity. For a complete
37 description of the input format, see @ruser{File structure}.
40 * Introduction to the LilyPond file structure::
41 * Score is a (single) compound musical expression::
42 * Nesting music expressions::
43 * On the un-nestedness of brackets and ties::
46 @node Introduction to the LilyPond file structure
47 @subsection Introduction to the LilyPond file structure
50 @cindex file structure
52 A basic example of a LilyPond input file is
55 \version @w{"@version{}"}
60 @var{ @dots{} compound music expression @dots{} } % all the music goes here!
67 There are many variations of this basic pattern, but this
68 example serves as a useful starting place.
75 Up to this point none of the examples you have seen have used a
76 @code{\score@{@}} command. This is because LilyPond automatically
77 adds the extra commands which are needed when you give it simple
78 input. LilyPond treats input like this:
87 as shorthand for this:
104 In other words, if the input contains a single music expression,
105 LilyPond will interpret the file as though the music expression
106 was wrapped up inside the commands shown above.
108 @cindex implicit contexts
109 @cindex contexts, implicit
111 @strong{A word of warning!} Many of the examples in the LilyPond
112 documentation will omit the @code{\new Staff} and @code{\new Voice}
113 commands, leaving them to be created implicitly. For simple
114 examples this works well, but for more complex examples, especially
115 when additional commands are used, the implicit creation of contexts
116 can give surprising results, maybe creating extra unwanted staves.
117 The way to create contexts explicitly is explained in
118 @ref{Contexts and engravers}.
120 @warning{When entering more than a few lines of music it is
121 advisable to always create staves and voices explicitly.}
123 For now, though, let us return to the first example and examine the
124 @code{\score} command, leaving the others to default.
126 A @code{\score} block must always contain exactly one music
127 expression. Remember that a music expression could be anything
128 from a single note to a huge compound expression like
133 @var{ @dots{} insert the whole score of a Wagner opera in here @dots{} }
139 Since everything is inside @code{@{ @dots{} @}}, it counts
140 as one music expression.
142 As we saw previously, the @code{\score} block can contain other
162 Note that these three commands -- @code{\header}, @code{\layout} and
163 @code{\midi} -- are special: unlike many other commands which begin
164 with a backward slash (@code{\}) they are @emph{not} music expressions
165 and are not part of any music expression. So they may be placed
166 inside a @code{\score} block or outside it. In fact, these commands
167 are commonly placed outside the @code{\score} block -- for example,
168 @code{\header} is often placed above the @code{\score} command, as the
169 example at the beginning of this section shows.
171 Two more commands you have not previously seen are
172 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
173 shown they will cause LilyPond to produce a printed output and a
174 MIDI output respectively. They are described fully in the
175 Notation Reference -- @ruser{Score layout}, and
176 @ruser{Creating MIDI output}.
178 @cindex scores, multiple
179 @cindex book block, implicit
180 @cindex implicit book block
183 You may code multiple @code{\score} blocks. Each will be
184 treated as a separate score, but they will be all combined into
185 a single output file. A @code{\book} command is not necessary
186 -- one will be implicitly created. However, if you would like
187 separate output files from one @file{.ly} file then the
188 @code{\book} command should be used to separate the different
189 sections: each @code{\book} block will produce a
190 separate output file.
194 Every @code{\book} block creates a separate output file (e.g., a
195 PDF file). If you haven't explicitly added one, LilyPond wraps
196 your entire input code in a @code{\book} block implicitly.
198 Every @code{\score} block is a separate chunk of music within a
201 @cindex layout block, effect of location
203 Every @code{\layout} block affects the @code{\score} or
204 @code{\book} block in which it appears -- i.e., a @code{\layout}
205 block inside a @code{\score} block affects only that @code{\score}
206 block, but a @code{\layout} block outside of a @code{\score} block
207 (and thus in a @code{\book} block, either explicitly or
208 implicitly) will affect every @code{\score} in that @code{\book}.
210 For details see @ruser{Multiple scores in a book}.
214 Another great shorthand is the ability to define variables, as
215 shown in @ref{Organizing pieces with variables}. All the
219 melody = \relative @{
228 When LilyPond looks at this file, it takes the value of
229 @code{melody} (everything after the equals sign) and inserts it
230 whenever it sees @code{\melody}. There's nothing special about
231 the name -- it could be @code{melody}, @code{global},
232 @code{keyTime}, @code{pianorighthand}, or something else.
233 Remember that you can use almost any name you like as long as it
234 contains just alphabetic characters and is distinct from LilyPond
235 command names. For more details, see @ref{Saving typing with
236 variables and functions}. The exact limitations on variable names
237 are detailed in @ruser{File structure}.
241 For a complete definition of the input format, see
242 @ruser{File structure}.
245 @node Score is a (single) compound musical expression
246 @subsection Score is a (single) compound musical expression
250 @cindex contents of a score block
251 @cindex score block, contents of
252 @cindex compound music expression
253 @cindex music expression, compound
255 We saw the general organization of LilyPond input files in the
256 previous section, @ref{Introduction to the LilyPond file structure}.
257 But we seemed to skip over the most important part: how do we figure
258 out what to write after @code{\score}?
260 We didn't skip over it at all. The big mystery is simply that
261 there @emph{is} no mystery. This line explains it all:
264 @emph{A @code{\score} block must contain exactly one music expression.}
268 To understand what is meant by a
269 music expression, you may find it useful to review the tutorial,
270 @ref{Music expressions explained}. In that section, we saw how to
271 build big music expressions from small pieces -- we started from
272 notes, then chords, etc. Now we're going to start from a big
273 music expression and work our way down. For simplicity, we'll use
274 just a singer and piano in our example. We don't need a
275 @code{StaffGroup} for this ensemble, which simply groups a number
276 of staves together with a bracket at the left, but we do need
277 staves for a singer and a piano, though.
282 \new Staff = "singer" <<
284 \new PianoStaff = "piano" <<
291 Here we have given names to the staves -- @qq{singer} and
292 @qq{piano}. This is not essential here, but it is a useful habit
293 to cultivate so that you can see at a glance what each stave is
296 Remember that we use @code{<< @dots{} >>} instead of @code{@{ @dots{} @}} to
297 show simultaneous music. This causes the vocal part and piano part
298 to appear one above the other in the score. The @code{<< @dots{} >>}
299 construct would not be necessary for the Singer staff in the example
300 above if it were going to contain only one sequential music
301 expression, but @code{<< @dots{} >>} rather than braces is necessary if
302 the music in the Staff is to contain two or more simultaneous
303 expressions, e.g. two simultaneous Voices, or a Voice with lyrics.
304 We're going to have a voice with lyrics, so angle brackets are
305 required. We'll add some real music later; for now let's just put
306 in some dummy notes and lyrics. If you've forgotten how to add lyrics
307 you may wish to review @code{\addlyrics} in @ref{Setting simple songs}.
309 @lilypond[verbatim,quote,ragged-right]
312 \new Staff = "singer" <<
313 \new Voice = "vocal" { c'1 }
316 \new PianoStaff = "piano" <<
317 \new Staff = "upper" { c'1 }
318 \new Staff = "lower" { c'1 }
325 Now we have a lot more details. We have the singer's staff: it
326 contains a @code{Voice} (in LilyPond, this term refers to a set of
327 notes, not necessarily vocal notes -- for example, a violin
328 generally plays one voice) and some lyrics. We also have a piano
329 staff: it contains an upper staff (right hand) and a lower staff
330 (left hand), although the lower staff has yet to be given a bass
333 At this stage, we could start filling in notes. Inside the curly
334 braces next to @code{\new Voice = "vocal"}, we could start writing
338 r4 d''8\noBeam g, c4 r
342 But if we did that, the @code{\score} section would get pretty
343 long, and it would be harder to understand what was happening. So
344 let's use variables instead. These were introduced at the end
345 of the previous section, remember? To ensure the contents of the
346 @code{text} variable are interpreted as lyrics we preface them with
347 @code{\lyricmode}. Like @code{\addlyrics}, this switches the input
348 mode to lyrics. Without that, LilyPond would try to interpret the
349 contents as notes, which would generate errors. (Several other
350 input modes are available, see @ruser{Input modes}.)
352 So, adding a few notes and a bass clef for the left hand, we now
353 have a piece of real music:
355 @lilypond[verbatim,quote,ragged-right]
356 melody = \relative { r4 d''8\noBeam g, c4 r }
357 text = \lyricmode { And God said, }
358 upper = \relative { <g' d g,>2~ <g d g,> }
359 lower = \relative { b,2 e }
363 \new Staff = "singer" <<
364 \new Voice = "vocal" { \melody }
367 \new PianoStaff = "piano" <<
368 \new Staff = "upper" { \upper }
369 \new Staff = "lower" {
379 When writing (or reading) a @code{\score} section, just take it
380 slowly and carefully. Start with the outer level, then work on
381 each smaller level. It also really helps to be strict with
382 indentation -- make sure that each item on the same level starts
383 on the same horizontal position in your text editor.
387 Notation Reference: @ruser{Structure of a score}.
390 @node Nesting music expressions
391 @subsection Nesting music expressions
393 @cindex staves, temporary
394 @cindex temporary staves
397 It is not essential to declare all staves at the beginning; they may
398 be introduced temporarily at any point. This is particularly useful
399 for creating ossia sections -- see @rglos{ossia}. Here is a simple
400 example showing how to introduce a new staff temporarily for the
401 duration of three notes:
403 @lilypond[verbatim,quote,ragged-right]
420 Note that the size of the clef is the same as a clef printed
421 following a clef change -- slightly smaller than the clef
422 at the beginning of the line. This is usual for clefs printed
423 in the middle of a line.
425 @cindex staff, positioning
427 The ossia section may be placed above the staff
430 @lilypond[verbatim,quote,ragged-right]
431 \new Staff = "main" {
438 alignAboveContext = #"main"
446 This example uses @code{\with}, which will be explained more
447 fully later. It is a means of modifying the default behavior
448 of a single Staff. Here it says that the new staff should be
449 placed above the staff called @qq{main} instead of the default
450 position which is below.
454 Ossia are often written without clef and without
455 time signature and are usually in a smaller font.
456 These require further commands which
457 have not yet been introduced. See @ref{Size of objects},
458 and @ruser{Ossia staves}.
461 @node On the un-nestedness of brackets and ties
462 @subsection On the un-nestedness of brackets and ties
464 @cindex brackets, nesting
465 @cindex bracket types
466 @cindex brackets, enclosing vs. marking
468 You have already met a number of different types of bracket and
469 bracket-like constructs in writing the input file to LilyPond.
470 These obey different rules which can be confusing at first.
471 Let's first review the different types of brackets and bracket-like
474 @c attempt to force this onto a new page
476 @multitable @columnfractions .3 .7
477 @headitem Bracket Type
479 @item @code{@{ @dots{} @}}
480 @tab Encloses a sequential segment of music
481 @item @code{< @dots{} >}
482 @tab Encloses the notes of a chord
483 @item @code{<< @dots{} >>}
484 @tab Encloses simultaneous music expressions
485 @item @code{( @dots{} )}
486 @tab Marks the start and end of a slur
487 @item @code{\( @dots{} \)}
488 @tab Marks the start and end of a phrasing slur
489 @item @code{[ @dots{} ]}
490 @tab Marks the start and end of a manual beam
493 To these we should add other constructs which generate lines
494 between or across notes: ties (marked by a tilde, @code{~}),
495 tuplets written as @code{\tuplet x/y @{ @dots{} @}}, and grace notes
496 written as @code{\grace @{ @dots{} @}}.
498 Outside LilyPond, the conventional use of brackets requires the
499 different types to be properly nested, like this, @code{<< [ @{ ( @dots{} )
500 @} ] >>}, with the closing brackets being encountered in exactly the
501 opposite order to the opening brackets. This @strong{is} a
502 requirement for the three types of bracket described by the word
503 @q{Encloses} in the table above -- they must nest properly. However,
504 the remaining bracket-like constructs, described with the word
505 @q{Marks} in the table above together with ties and tuplets, do
506 @strong{not} have to nest properly with any of the brackets or
507 bracket-like constructs. In fact, these are not brackets in
508 the sense that they enclose something -- they are simply markers to
509 indicate where something starts and ends.
511 So, for example, a phrasing slur can start before a manually
512 inserted beam and end before the end of the beam -- not very
513 musical, perhaps, but possible:
515 @lilypond[quote,verbatim,ragged-right]
516 \relative { g'8\( a b[ c b\) a] g4 }
519 In general, different kinds of brackets, bracket-like constructs,
520 and those implied by tuplets, ties and grace notes, may be mixed
521 freely. This example shows a beam extending into a tuplet (line 1),
522 a slur extending into a tuplet (line 2), a beam and a slur
523 extending into a tuplet, a tie crossing two tuplets, and a
524 phrasing slur extending out of a tuplet (lines 3 and 4).
526 @lilypond[quote,verbatim,ragged-right]
528 r16[ g' \tuplet 3/2 { r16 e'8] }
529 g,16( a \tuplet 3/2 { b16 d) e }
530 g,8[( a \tuplet 3/2 { b8 d) e~] } |
531 \tuplet 5/4 { e32\( a, b d e } a4.\)
536 @node Voices contain music
537 @section Voices contain music
539 Singers need voices to sing, and so does LilyPond.
540 The actual music for all instruments in a score
541 is contained in Voices -- the most fundamental
542 of all LilyPond's concepts.
545 * I'm hearing Voices::
546 * Explicitly instantiating voices::
547 * Voices and vocals::
550 @node I'm hearing Voices
551 @subsection I'm hearing Voices
555 @cindex multiple voices
556 @cindex voices, multiple
557 @cindex Voice context
558 @cindex context, Voice
559 @cindex simultaneous music
560 @cindex music, simultaneous
561 @cindex concurrent music
562 @cindex music, concurrent
563 @cindex voices vs. chords
564 @cindex chords vs. voices
566 The lowest, most fundamental or innermost layers in a LilyPond
567 score are called @q{Voice contexts} or just @q{Voices} for short.
568 Voices are sometimes called @q{layers} in other notation
571 In fact, a Voice layer or context is the only one which can contain
572 music. If a Voice context is not explicitly declared one is created
573 automatically, as we saw at the beginning of this chapter. Some
574 instruments such as an Oboe can play only one note at a time. Music
575 written for such instruments requires just a single voice. Instruments
576 which can play more than one note at a time like the piano will often
577 require multiple voices to encode the different concurrent notes and
578 rhythms they are capable of playing.
580 A single voice can contain many notes in a chord, of course,
581 so when exactly are multiple voices needed? Look first at
582 this example of four chords:
584 @lilypond[quote,verbatim,ragged-right]
587 <d' g>4 <d fis> <d a'> <d g>
591 This can be expressed using just the single angle bracket chord
592 symbols, @code{< @dots{} >}, and for this just a single voice is
593 needed. But suppose the F-sharp were actually an eighth-note
594 followed by an eighth-note G, a passing note on the way to the A?
595 Now we have two notes which start at the same time but have
596 different durations: the quarter-note D and the eighth-note
597 F-sharp. How are these to be coded? They cannot be written as
598 a chord because all the notes in a chord must have the same
599 duration. And they cannot be written as two sequential notes
600 as they need to start at the same time. This is when two
603 Let us see how this is done in LilyPond input syntax.
608 The easiest way to enter fragments with more than one voice on a
609 staff is to enter each voice as a sequence (with @code{@{ @dots{} @}}),
610 and combine them simultaneously with angle brackets, @code{<< @dots{} >>}.
611 The fragments must also be separated with double backward slashes,
612 @code{\\}, to place them in separate voices. Without these, the
613 notes would be entered into a single voice, which would usually
614 cause errors. This technique is particularly suited to pieces of
615 music which are largely homophonic with occasional short sections
618 Here's how we split the chords above into two voices and add both
619 the passing note and a slur:
621 @lilypond[quote,verbatim,ragged-right]
624 % Voice = "1" Voice = "2"
625 << { g'4 fis8( g) a4 g } \\ { d4 d d d } >>
629 Notice how the stems of the second voice now point down.
631 Here's another simple example:
633 @lilypond[quote,verbatim,ragged-right]
636 % Voice = "1" Voice = "2"
637 << { r4 g' g4. a8 } \\ { d,2 d4 g } >> |
638 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
639 << { a2. r4 } \\ { fis2. s4 } >> |
643 It is not necessary to use a separate @code{<< \\ >>} construct
644 for each bar. For music with few notes in each bar this layout
645 can help the legibility of the code, but if there are many
646 notes in each bar it may be better to split out each voice
647 separately, like this:
649 @lilypond[quote,verbatim,ragged-right]
652 \relative { % Voice = "1"
657 \relative { % Voice = "2"
666 @cindex voices, naming
667 @cindex voices crossing brackets
668 @cindex slurs crossing brackets
669 @cindex ties crossing brackets
671 This example has just two voices, but the same construct may be
672 used to encode three or more voices by adding more back-slash
675 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
676 The first contexts set the @emph{outer} voices, the highest
677 voice in context @code{"1"} and the lowest voice in context
678 @code{"2"}. The inner voices go in contexts @code{"3"} and
679 @code{"4"}. In each of these contexts, the vertical direction
680 of slurs, stems, ties, dynamics etc., is set appropriately.
682 @lilypond[quote,verbatim]
683 \new Staff \relative {
686 % Voice = "1" Voice = "2" Voice = "3"
687 << { g4 f e } \\ { r8 e4 d c8~ } >> |
688 << { d2 e } \\ { c8 b16 a b8 g~ 2 } \\ { s4 b c2 } >> |
693 If you prefer entering the voices in a different order, like top
694 to bottom, you can specify the respective voice numbers in front
695 of one @code{<< @dots{} >>} construct using the @code{\voices}
698 @lilypond[quote,verbatim]
699 \new Staff \relative {
702 % Voice = "1" Voice = "2"
703 << { g4 f e } \\ { r8 e4 d c8~ } >> |
705 % Voice = "1" Voice = "3" Voice = "2"
706 << { d2 e } \\ { s4 b c2 } \\ { c8 b16 a b8 g~ 2 } >> |
710 These voices are all separate from the main voice that contains
711 the notes just outside the @code{<< @dots{} >>} construct. Let's call
712 this the @emph{simultaneous construct}. Slurs and ties may only
713 connect notes within the same voice, so slurs and ties cannot go
714 into or out of a simultaneous construct. Conversely,
715 parallel voices from separate simultaneous constructs on the same
716 staff are the same voice. Other voice-related properties also
717 carry across simultaneous constructs. Here is the same example,
718 with different colors and note heads for each voice. Note that
719 changes in one voice do not affect other voices, but they do
720 persist in the same voice later. Note also that tied notes may be
721 split across the same voices in two constructs, shown here in the
724 @lilypond[quote,verbatim]
725 \new Staff \relative {
754 @funindex \voiceOneStyle
755 @funindex \voiceTwoStyle
756 @funindex \voiceThreeStyle
757 @funindex \voiceFourStyle
758 @funindex \voiceNeutralStyle
760 The commands @code{\voiceXXXStyle} are mainly intended for use in
761 educational documents such as this one. They modify the color
762 of the note head, the stem and the beams, and the style of the
763 note head, so that the voices may be easily distinguished.
764 Voice one is set to red diamonds, voice two to blue triangles,
765 voice three to green crossed circles, and voice four (not used
766 here) to magenta crosses; @code{\voiceNeutralStyle} (also not
767 used here) reverts the style back to the default.
768 We shall see later how commands like these may be created by the
770 See @ref{Visibility and color of objects} and
771 @ref{Using variables for layout adjustments}.
773 @cindex polyphony and relative note entry
774 @cindex relative note entry and polyphony
776 Polyphony does not change the relationship of notes within a
777 @code{\relative} block. Each note is still calculated relative to
778 the note immediately preceding it, or to the first note of the
779 preceding chord. So in
782 \relative @{ noteA << < noteB noteC > \\ noteD >> noteE @}
786 @code{noteB} is relative to @code{noteA} @*
787 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
788 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
790 @code{noteE} is relative to @code{noteD}, not @code{noteA}.
792 An alternative way, which may be clearer if the notes in the
793 voices are widely separated, is to place a @code{\relative}
794 command at the start of each voice:
797 \relative @{ noteA @dots{} @}
799 \relative @{ < noteB noteC > @dots{} @}
801 \relative @{ noteD @dots{} @}
803 \relative @{ noteE @dots{} @}
806 Let us finally analyze the voices in a more complex piece of music.
807 Here are the notes from the first two bars of the second of Chopin's
808 Deux Nocturnes, Op 32. This example will be used at later stages in
809 this and the next chapter to illustrate several techniques for
810 producing notation, so please ignore for now anything in the
811 underlying code which looks mysterious and concentrate just on the
812 music and the voices -- the complications will all be explained in
815 @c The following should appear as music without code
816 @lilypond[quote,ragged-right]
817 \new Staff \relative {
819 \voices 1,2,4 % No voice three
824 % Ignore these for now - they are explained in Ch 4
825 \once \override NoteColumn.force-hshift = #0
827 \once \override NoteColumn.force-hshift = #0.5
832 \override NoteColumn.force-hshift = #0
840 The direction of the stems is often used to indicate the continuity of
841 two simultaneous melodic lines. Here the stems of the highest notes
842 are all pointing up and the stems of the lower notes are all pointing
843 down. This is the first indication that more than one voice is
846 But the real need for multiple voices arises when notes
847 which start at the same time have different durations.
848 Look at the notes which start at beat three in the first
849 bar. The A-flat is a dotted quarter note, the F is a
850 quarter note and the D-flat is a half note. These
851 cannot be written as a chord as all the notes in a chord
852 must have the same duration. Neither can they be written
853 as sequential notes, as they must start at the same time.
854 This section of the bar requires three voices, and the
855 normal practice would be to write the whole bar as three
856 voices, as shown below, where we have used different note heads
857 and colors for the three voices. Again, the code behind this
858 example will be explained later, so ignore anything you do
861 @c The following should appear as music without code
862 @c The three voice styles should be defined in -init
863 @lilypond[quote,ragged-right]
864 \new Staff \relative {
866 \voices 1,2,4 % No Voice three (we want stems down)
874 % Ignore these for now - they are explained in Ch 4
875 \once \override NoteColumn.force-hshift = #0
877 \once \override NoteColumn.force-hshift = #0.5
882 \override NoteColumn.force-hshift = #0
891 Let us try to encode this music from scratch. As we
892 shall see, this encounters some difficulties. We begin as
893 we have learnt, using the @code{<< \\ >>} construct to
894 enter the music of the first bar in three voices:
896 @lilypond[quote,verbatim,ragged-right]
897 \new Staff \relative {
900 { c''2 aes4. bes8 } \\ { <ees, c>2 des } \\ { aes'2 f4 fes }
907 @cindex voices and stem directions
908 @cindex stem directions and voices
911 The stem directions are automatically assigned with the
912 odd-numbered voices taking upward stems and the even-numbered
913 voices downward ones. The stems for voices 1 and 2 are right,
914 but the stems in voice 3 should go down in this particular piece
915 of music. We can correct this by skipping voice three
916 and placing the music in voice four. This could be done by simply
917 adding another pair of @code{\\}, but we use the @code{\voices}
918 command instead (which would also allow us to enter the voices in
919 different order if we preferred doing that):
921 @lilypond[quote,verbatim,ragged-right]
922 \new Staff \relative {
924 \voices 1,2,4 % Omit Voice three
937 We see that this fixes the stem direction, but the horizontal
938 placement of notes is not what we want. LilyPond shifts the
939 inner notes when they or their stems would collide with outer
940 voices, but this is not appropriate for piano music. In other
941 situations, the shifts LilyPond applies might fail to clear
942 the collisions. LilyPond provides several ways to adjust the
943 horizontal placing of notes. We are not quite ready yet to see
944 how to correct this, so we shall leave this problem until a
945 later section --- see the @code{force-hshift} property in
946 @ref{Fixing overlapping notation}.
948 @warning{Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be
949 created @q{across} voices.}
953 Notation Reference: @ruser{Multiple voices}.
956 @node Explicitly instantiating voices
957 @subsection Explicitly instantiating voices
961 @funindex \voiceThree
965 @cindex voice contexts, creating
967 Voice contexts can also be created manually
968 inside a @code{<< >>} block to create polyphonic music, using
969 @code{\voiceOne} @dots{} @code{\voiceFour} to indicate the required
970 directions of stems, slurs, etc. In longer scores this method
971 is clearer, as it permits the voices to be separated and to be
972 given more descriptive names.
974 Specifically, the construct @code{<< \\ >>} which we used in
975 the previous section:
980 << @{ e'4 f g a @} \\ @{ c,4 d e f @} >>
990 \new Voice = "1" @{ \voiceOne \relative @{ e'4 f g a @} @}
991 \new Voice = "2" @{ \voiceTwo \relative @{ c'4 d e f @} @}
995 Both of the above would produce
997 @c The following example should not display the code
998 @lilypond[ragged-right,quote]
1000 \new Voice = "1" { \voiceOne \relative { e'4 f g a } }
1001 \new Voice = "2" { \voiceTwo \relative { c'4 d e f } }
1005 @cindex voices, reverting to single
1006 @cindex reverting to a single voice
1008 The @code{\voiceXXX} commands set the direction of stems, slurs,
1009 ties, articulations, text annotations, augmentation dots of dotted
1010 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
1011 make these objects point upwards, while @code{\voiceTwo} and
1012 @code{\voiceFour} make them point downwards. These commands also
1013 generate a horizontal shift for each voice when this is required
1014 to avoid clashes of note heads. The command @code{\oneVoice}
1015 reverts the settings back to the normal values for a single voice.
1017 Let us see in some simple examples exactly what effect
1018 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
1019 markup, ties, slurs, and dynamics:
1021 @lilypond[quote,ragged-right,verbatim]
1023 % Default behavior or behavior after \oneVoice
1024 c'4 d8~ 8 e4( f | g4 a) b-> c |
1028 @lilypond[quote,ragged-right,verbatim]
1031 c'4 d8~ 8 e4( f | g4 a) b-> c |
1033 c,4 d8~ 8 e4( f | g4 a) b-> c |
1037 @lilypond[quote,ragged-right,verbatim]
1040 c'4 d8~ 8 e4( f | g4 a) b-> c |
1042 c,4 d8~ 8 e4( f | g4 a) b-> c |
1046 Now let's look at four different ways to notate the same passage of
1047 polyphonic music, each of which is advantageous in different
1048 circumstances, using the example from the previous section.
1050 An expression that appears directly inside a @code{<< >>} belongs to the
1051 main voice (but, note, @strong{not} in a @code{<< \\ >>} construct).
1052 This is useful when extra voices appear while the main voice is playing.
1053 Here is a more correct rendition of our example. The red diamond-shaped
1054 notes demonstrate that the main melody is now in a single voice context,
1055 permitting a phrasing slur to be drawn over them.
1057 @lilypond[quote,ragged-right,verbatim]
1058 \new Staff \relative {
1060 % This section is homophonic
1062 % Start simultaneous section of three voices
1064 % Continue the main voice in parallel
1065 { g4 f e | d2 e) | }
1066 % Initiate second voice
1068 % Set stems, etc., down
1070 r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
1072 % Initiate third voice
1074 % Set stems, etc, up
1082 @cindex voices, continued
1085 The @code{\voices} command can also be used for continuing a main
1086 voice into the simultaneous construct:
1088 @lilypond[quote,ragged-right,verbatim]
1089 \new Staff \relative {
1090 \new Voice = "main" {
1092 % This section is homophonic
1094 % Start simultaneous section of three voices
1097 % Continue the main voice in parallel
1098 { g4 f e | d2 e) | }
1099 % Initiate second voice
1101 % Set stems, etc., down
1102 { r8 e4 d c8~ | 8 b16 a b8 g~ 2 | }
1104 % Initiate third voice
1105 % Set stems, etc, up
1113 @cindex nesting music expressions
1114 @cindex nesting simultaneous constructs
1115 @cindex nesting voices
1116 @cindex voices, temporary
1117 @cindex voices, nesting
1119 More deeply nested polyphony constructs are possible, and if a
1120 voice appears only briefly this might be a more natural way to
1123 @lilypond[quote,ragged-right,verbatim]
1124 \new Staff \relative {
1127 { g4 f e | d2 e) | }
1132 { c8 b16 a b8 g~ 2 | }
1143 @cindex spacing notes
1145 This method of nesting new voices briefly is useful
1146 when only small sections of the music
1147 are polyphonic, but when the whole staff is largely polyphonic
1148 it can be clearer to use multiple voices throughout, using
1149 spacing notes to step over sections where the voice is silent,
1152 @lilypond[quote,ragged-right,verbatim]
1153 \new Staff \relative <<
1154 % Initiate first voice
1157 c'16^( d e f g4 f e | d2 e) |
1159 % Initiate second voice
1161 % Set stems, etc, down
1163 s4 r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
1165 % Initiate third voice
1167 % Set stems, etc, up
1174 @subsubheading Note columns
1177 @cindex note collisions
1178 @cindex collisions, notes
1179 @cindex shift commands
1183 @funindex \shiftOnnn
1185 Closely spaced notes in a chord, or notes occurring at the same
1186 time in different voices, are arranged in two, occasionally more,
1187 columns to prevent the note heads overlapping. These are called
1188 note columns. There are separate columns for each voice, and
1189 the currently specified voice-dependent shift is applied to the
1190 note column if there would otherwise be a collision. This can
1191 be seen in the example above. In bar 2 the C in voice two is
1192 shifted to the right relative to the D in voice one, and in the
1193 final chord the C in voice three is also shifted to the right
1194 relative to the other notes.
1196 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1197 @code{\shiftOff} commands specify the degree to which notes and
1198 chords of the voice should be shifted if a collision
1199 would otherwise occur. By default, the outer voices (normally
1200 voices one and two) have @code{\shiftOff} specified, while the
1201 inner voices (three and four) have @code{\shiftOn} specified.
1202 When a shift is applied, voices one and three are shifted to
1203 the right and voices two and four to the left.
1205 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1206 levels which may be specified temporarily to resolve collisions
1207 in complex situations -- see @ref{Real music example}.
1209 A note column can contain just one note (or chord) from a voice
1210 with stems up and one note (or chord) from a voice with stems
1211 down. If notes from two voices which have their stems in the
1212 same direction are placed at the same position and both voices
1213 have no shift or the same shift specified, the error message
1214 @qq{This voice needs a @code{@bs{}voiceXx} or @code{@bs{}shiftXx} setting}
1220 @ref{Moving objects}.
1223 @ruser{Multiple voices}.
1226 @node Voices and vocals
1227 @subsection Voices and vocals
1229 Vocal music presents a special difficulty: we need to combine two
1230 expressions -- notes and lyrics.
1232 @funindex \new Lyrics
1235 @cindex Lyrics context, creating
1236 @cindex lyrics, linking to voice
1238 You have already seen the @code{\addlyrics@{@}} command, which
1239 handles simple scores well. However, this technique is
1240 quite limited. For more complex music, you must introduce the
1241 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1243 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1244 name assigned to the Voice.
1246 @lilypond[quote,verbatim]
1248 \new Voice = "one" {
1252 c''4 b8. a16 | g4. f8 | e4 d | c2 |
1255 \new Lyrics \lyricsto "one" {
1256 No more let | sins and | sor -- rows | grow. |
1261 Note that the lyrics must be linked to a @code{Voice} context,
1262 @emph{not} a @code{Staff} context. This is a case where it is
1263 necessary to create @code{Staff} and @code{Voice} contexts
1266 @cindex lyrics and beaming
1267 @cindex beaming and lyrics
1268 @funindex \autoBeamOff
1270 The automatic beaming which LilyPond uses by default works well
1271 for instrumental music, but not so well for music with lyrics,
1272 where beaming is either not required at all or is used to indicate
1273 melismata in the lyrics. In the example above we use the command
1274 @code{\autoBeamOff} to turn off the automatic beaming.
1276 @funindex \new ChoirStaff
1277 @funindex ChoirStaff
1278 @funindex \lyricmode
1279 @cindex vocal score structure
1282 Let us reuse the earlier example from Judas Maccabæus to
1283 illustrate this more flexible technique. We first recast
1284 it to use variables so the music and lyrics can be separated
1285 from the staff structure. We also introduce a ChoirStaff
1286 bracket. The lyrics themselves must be introduced with
1287 @code{\lyricmode} to ensure they are interpreted as lyrics
1290 @lilypond[quote,verbatim]
1291 global = { \key f \major \time 6/8 \partial 8 }
1293 SopOneMusic = \relative {
1294 c''8 | c8([ bes)] a a([ g)] f | f'4. b, | c4.~ 4
1296 SopOneLyrics = \lyricmode {
1297 Let | flee -- cy flocks the | hills a -- dorn, __
1299 SopTwoMusic = \relative {
1300 r8 | r4. r4 c'8 | a'8([ g)] f f([ e)] d | e8([ d)] c bes'
1302 SopTwoLyrics = \lyricmode {
1303 Let | flee -- cy flocks the | hills a -- dorn,
1309 \new Voice = "SopOne" {
1313 \new Lyrics \lyricsto "SopOne" {
1318 \new Voice = "SopTwo" {
1322 \new Lyrics \lyricsto "SopTwo" {
1330 This is the basic structure of all vocal scores. More staves may be
1331 added as required, more voices may be added to the staves, more verses
1332 may be added to the lyrics, and the variables containing the music can
1333 easily be placed in separate files should they become too long.
1335 @cindex hymn structure
1336 @cindex SATB structure
1337 @cindex vocal scores with multiple verses
1338 @cindex multiple vocal verses
1339 @cindex verses, multiple vocal
1341 Here is an example of the first line of a hymn with four
1342 verses, set for SATB. In this case the words for all four
1343 parts are the same. Note how we use variables to separate the
1344 music notation and words from the staff structure. See too
1345 how a variable, which we have chosen to call @q{keyTime}, is used
1346 to hold several commands for use within the two staves. In other
1347 examples this is often called @q{global}.
1349 @lilypond[quote,verbatim]
1350 keyTime = { \key c \major \time 4/4 \partial 4 }
1352 SopMusic = \relative { c'4 | e4. e8 g4 g | a4 a g }
1353 AltoMusic = \relative { c'4 | c4. c8 e4 e | f4 f e }
1354 TenorMusic = \relative { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1355 BassMusic = \relative { c4 | c4. c8 c4 c | f8 g a b c4 }
1358 \lyricmode { E -- | ter -- nal fa -- ther, | strong to save, }
1360 \lyricmode { O | Christ, whose voice the | wa -- ters heard, }
1362 \lyricmode { O | Ho -- ly Spi -- rit, | who didst brood }
1364 \lyricmode { O | Tri -- ni -- ty of | love and pow'r }
1370 \new Voice = "Sop" { \voiceOne \keyTime \SopMusic }
1371 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1372 \new Lyrics \lyricsto "Sop" { \VerseOne }
1373 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1374 \new Lyrics \lyricsto "Sop" { \VerseThree }
1375 \new Lyrics \lyricsto "Sop" { \VerseFour }
1379 \new Voice = "Tenor" { \voiceOne \keyTime \TenorMusic }
1380 \new Voice = "Bass" { \voiceTwo \BassMusic }
1388 Notation Reference: @ruser{Vocal music}.
1391 @node Contexts and engravers
1392 @section Contexts and engravers
1394 Contexts and engravers have been mentioned informally
1395 in earlier sections; we now must look at
1396 these concepts in more detail, as they are important
1397 in the fine-tuning of LilyPond output.
1401 * Contexts explained::
1402 * Creating contexts::
1403 * Engravers explained::
1404 * Modifying context properties::
1405 * Adding and removing engravers::
1408 @node Contexts explained
1409 @subsection Contexts explained
1411 @cindex contexts explained
1413 When music is printed, many notational elements which do not
1414 appear explicitly in the input file must be added to the
1415 output. For example, compare the input and output of the
1418 @lilypond[quote,verbatim]
1419 \relative { cis''4 cis2. | a4 a2. | }
1422 The input is rather sparse, but in the output, bar lines,
1423 accidentals, clef, and time signature have been added. When
1424 LilyPond @emph{interprets} the input the musical information
1425 is parsed from left to right, similar to the way a performer
1426 reads the score. While reading the input, the program remembers
1427 where measure boundaries are, and which pitches require explicit
1428 accidentals. This information must be held on several levels.
1429 For example, an accidental affects only a single staff, while
1430 a bar line must be synchronized across the entire score.
1432 Within LilyPond, these rules and bits of information are grouped in
1433 @emph{Contexts}. We have already introduced the @code{Voice} context.
1434 Others are the @code{Staff} and @code{Score} contexts. Contexts are
1435 hierarchical to reflect the hierarchical nature of a musical score.
1436 For example: a @code{Staff} context can contain many @code{Voice}
1437 contexts, and a @code{Score} context can contain many @code{Staff}
1441 @sourceimage{context-example,5cm,,}
1444 Each context has the responsibility for enforcing some notation rules,
1445 creating some notation objects and maintaining the associated
1446 properties. For example, the @code{Voice} context may introduce an
1447 accidental and then the @code{Staff} context maintains the rule to
1448 show or suppress the accidental for the remainder of the measure.
1450 As another example, the synchronization of bar lines is, by default,
1451 handled in the @code{Score} context.
1452 However, in some music we may not want the bar lines to be
1453 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1454 In such cases, we must modify the default settings of the
1455 @code{Score} and @code{Staff} contexts.
1457 For very simple scores, contexts are created implicitly, and you need
1458 not be aware of them. For larger pieces, such as anything with more
1459 than one staff, they must be
1460 created explicitly to make sure that you get as many staves as you
1461 need, and that they are in the correct order. For typesetting pieces
1462 with specialized notation, it is usual to modify existing, or
1463 even to define totally new, contexts.
1465 In addition to the @code{Score,} @code{Staff} and
1466 @code{Voice} contexts there are contexts which fit between
1467 the score and staff levels to control staff groups, such as the
1468 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1469 are also alternative staff and voice contexts, and contexts for
1470 lyrics, percussion, fret boards, figured bass, etc.
1472 The names of all context types are formed from one or more
1473 words, each word being capitalized and joined immediately to the
1474 preceding word with no hyphen or underscore, e.g.,
1475 @code{GregorianTranscriptionStaff}.
1479 Notation Reference: @ruser{Contexts explained}.
1482 @node Creating contexts
1483 @subsection Creating contexts
1486 @cindex new contexts
1487 @cindex creating contexts
1488 @cindex contexts, creating
1490 In an input file, a score block (introduced with a @code{\score}
1491 command) contains a single music expression; but it can also contain
1492 associated output definitions too -- either a @code{\layout} block, a
1493 @code{\midi} block or both. The @code{Score} context is usually left to
1494 be created automatically when the interpretation of that music
1497 For scores with only one voice and one staff, the @code{Voice} and
1498 @code{Staff} contexts may also be left to be created automatically,
1499 but for more complex scores it is necessary to create them by hand.
1500 The simplest command that does this is @code{\new}. It is prepended
1501 to a music expression, for example
1504 \new @var{type} @var{music-expression}
1508 where @var{type} is a context name (like @code{Staff} or
1509 @code{Voice}). This command creates a new context, and starts
1510 interpreting the @var{music-expression} within that context.
1512 @warning{@bs{}@code{new Score} should not be used as the essential
1513 top-level @code{Score} context is created automatically when the music
1514 expression within the @bs{}@code{score} block is interpreted. Score-wide
1515 default values of context properties can be changed within the
1516 @bs{}@code{layout} block. See @ref{Modifying context properties}}
1518 You have seen many practical examples which created new
1519 @code{Staff} and @code{Voice} contexts in earlier sections, but
1520 to remind you how these commands are used in practice, here's an
1521 annotated real-music example:
1523 @lilypond[quote,verbatim,ragged-right]
1524 \score { % start of single compound music expression
1525 << % start of simultaneous staves section
1527 \new Staff { % create RH staff
1530 \new Voice { % create voice for RH notes
1531 \relative { % start of RH notes
1537 \new Staff << % create LH staff; needs two simultaneous voices
1540 \new Voice { % create LH voice one
1542 \relative { % start of LH voice one notes
1543 g8 <bes d> ees, <g c> |
1544 g8 <bes d> ees, <g c> |
1545 } % end of LH voice one notes
1546 } % end of LH voice one
1547 \new Voice { % create LH voice two
1549 \relative { % start of LH voice two notes
1552 } % end of LH voice two notes
1553 } % end of LH voice two
1554 >> % end of LH staff
1555 >> % end of simultaneous staves section
1556 } % end of single compound music expression
1559 (Note how all the statements which open a block with either a
1560 curly bracket, @code{@{}, or double angle brackets, @code{<<},
1561 are indented by two further spaces, and the corresponding
1562 closing bracket is indented by exactly the same amount. While
1563 this is not required, following this practice will greatly
1564 reduce the number of @q{unmatched bracket} errors, and is
1565 strongly recommended. It enables the structure of the music to
1566 be seen at a glance, and any unmatched brackets will be obvious.
1567 Note too how the LH staff is created using double angle brackets
1568 because it requires two voices for its music, whereas the RH staff
1569 is created with a single music expression surrounded by curly
1570 brackets because it requires only one voice.)
1572 @cindex contexts, naming
1573 @cindex naming contexts
1575 The @code{\new} command may also give an identifying name to the
1576 context to distinguish it from other contexts of the same type,
1579 \new @var{type} = @var{id} @var{music-expression}
1582 Note the distinction between the name of the context type,
1583 @code{Staff}, @code{Voice}, etc, and the identifying name of a
1584 particular instance of that type, which can be any sequence of letters
1585 invented by the user. Digits and spaces can also be used in the
1586 identifying name, but then it has to be placed in quotes,
1587 i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
1588 The identifying name is used to
1589 refer back to that particular instance of a context. We saw this in
1590 use in the section on lyrics, see @ref{Voices and vocals}.
1594 Notation Reference: @ruser{Creating and referencing contexts}.
1597 @node Engravers explained
1598 @subsection Engravers explained
1602 Every mark on the printed output of a score produced by LilyPond
1603 is produced by an @code{Engraver}. Thus there is an engraver
1604 to print staves, one to print note heads, one for stems, one for
1605 beams, etc, etc. In total there are over 120 such engravers!
1606 Fortunately, for most scores it is not necessary to know about
1607 more than a few, and for simple scores you do not need to know
1610 Engravers live and operate in Contexts. Engravers such as the
1611 @code{Metronome_mark_engraver}, whose action and output apply to the
1612 score as a whole, operate in the highest level context -- the
1613 @code{Score} context.
1615 The @code{Clef_engraver} and @code{Key_engraver} are to be
1616 found in every @code{Staff} Context, as different staves may require
1617 different clefs and keys.
1619 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1620 in every @code{Voice} context, the lowest level context of all.
1622 Each engraver processes the particular objects associated
1623 with its function, and maintains the properties that relate
1624 to that function. These properties, like the properties
1625 associated with contexts, may be modified to change the
1626 operation of the engraver or the appearance of those elements
1627 in the printed score.
1629 Engravers all have compound names formed from words which
1630 describe their function. Just the first word is capitalized,
1631 and the remainder are joined to it with underscores. Thus
1632 the @code{Staff_symbol_engraver} is responsible for creating the
1633 lines of the staff, the @code{Clef_engraver} determines and sets
1634 the pitch reference point on the staff by drawing a clef symbol.
1636 Here are some of the most common engravers together with their
1637 function. You will see it is usually easy to guess the function
1638 from the name, or vice versa.
1640 @multitable @columnfractions .3 .7
1643 @item Accidental_engraver
1644 @tab Makes accidentals, cautionary and suggested accidentals
1649 @item Completion_heads_engraver
1650 @tab Splits notes which cross bar lines
1651 @item Dynamic_engraver
1652 @tab Creates hairpins and dynamic texts
1653 @item Forbid_line_break_engraver
1654 @tab Prevents line breaks if a musical element is still active
1656 @tab Creates the key signature
1657 @item Metronome_mark_engraver
1658 @tab Engraves metronome marking
1659 @item Note_heads_engraver
1660 @tab Engraves note heads
1663 @item Staff_symbol_engraver
1664 @tab Engraves the five (by default) lines of the staff
1666 @tab Creates stems and single-stem tremolos
1667 @item Time_signature_engraver
1668 @tab Creates time signatures
1673 We shall see later how the output of LilyPond can be changed
1674 by modifying the action of Engravers.
1678 Internals reference: @rinternals{Engravers and Performers}.
1681 @node Modifying context properties
1682 @subsection Modifying context properties
1684 @cindex context properties
1685 @cindex context properties, modifying
1686 @cindex modifying context properties
1690 Contexts are responsible for holding the values of a number of
1691 context @emph{properties}. Many of them can be changed to
1692 influence the interpretation of the input and so change the
1693 appearance of the output. They are changed by the
1694 @code{\set} command. This takes the form
1697 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1700 Where the @emph{ContextName} is usually @code{Score},
1701 @code{Staff} or @code{Voice}. It may be omitted,
1702 in which case the current context (typically @code{Voice}) is assumed.
1704 The names of context properties consist of words joined
1705 together with no hyphens or underscores, all except the
1706 first having a capital letter. Here are a few examples
1707 of some commonly used ones. There are many more.
1709 @c attempt to force this onto a new page
1711 @multitable @columnfractions .25 .15 .45 .15
1712 @headitem propertyName
1718 @tab If true, set extra natural signs before accidentals
1719 @tab @code{#t}, @code{#f}
1720 @item currentBarNumber
1722 @tab Set the current bar number
1726 @tab If true, print slurs both above and below notes
1727 @tab @code{#t}, @code{#f}
1728 @item instrumentName
1730 @tab Set the name to be placed at the start of the staff
1731 @tab @code{"Cello I"}
1734 @tab Increase or decrease the font size
1738 @tab Set the text to print before the start of a verse
1743 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1744 an Integer is a positive whole number, a Real is a positive
1745 or negative decimal number, and text is enclosed in double
1746 apostrophes. Note the occurrence of hash signs,
1747 (@code{#}), in two different places -- as part of the Boolean
1748 value before the @code{t} or @code{f}, and before @emph{value}
1749 in the @code{\set} statement. So when a Boolean is being
1750 entered you need to code two hash signs, e.g., @code{##t}.
1752 @cindex properties operating in contexts
1753 @cindex setting properties within contexts
1755 Before we can set any of these properties we need to know
1756 in which context they operate. Sometimes this is obvious,
1757 but occasionally it can be tricky. If the wrong context
1758 is specified, no error message is produced, but the expected
1759 action will not take place. For example, the
1760 @code{clefGlyph} clearly lives in the @code{Staff} context, since
1761 it is the staff's clef glyph that is to be changed.
1762 In this example the first staff's clef is printed correctly, but not the
1763 second -- which prints the default treble clef instead of the
1764 expected bass (or F) clef -- because we omitted the context name.
1766 @lilypond[quote,verbatim,ragged-right]
1768 \new Staff \relative {
1769 \set Staff.clefGlyph = "clefs.C"
1772 \new Staff \relative {
1773 \set clefGlyph = "clefs.F" % Wrong!
1779 Remember the default context name is @code{Voice}, so the second
1780 @code{\set} command set the property @code{clefGlyph} in the
1781 @code{Voice} context to @code{clefs.F}, but as LilyPond does not look
1782 for any such property in the @code{Voice} context, no
1783 further action took place. This is not an error, and no error
1784 message is logged in the log file.
1786 Similarly, if the property name is mis-spelt no error message is
1787 produced, and clearly the expected action cannot be performed. In
1788 fact, you can set any (fictitious) @q{property} using any name you
1789 like in any context that exists by using the @code{\set} command. But
1790 if the name is not known to LilyPond it will not cause any action to
1791 be taken. Some text editors with special support for LilyPond input
1792 files document property names with bullets when you hover them with
1793 the mouse, like JEdit with LilyPondTool, or highlight unknown property
1794 names differently, like ConTEXT. If you do not use an editor with
1795 such features, it is recommended to check the property name in the
1796 Internals Reference: see @rinternals{Tunable context properties}, or
1797 @rinternals{Contexts}.
1799 The @code{clefGlyph} property will take effect only
1800 if it is set in the @code{Staff} context, but
1801 some properties can be set in more than one context.
1802 For example, the property @code{extraNatural} is by
1803 default set to ##t (true) for all staves.
1804 If it is set to ##f (false) in one particular @code{Staff}
1805 context it applies just to the accidentals on that staff.
1806 If it is set to false in the @code{Score} context
1807 it applies to all staves.
1809 So this turns off extra naturals in one staff:
1811 @lilypond[quote,verbatim,ragged-right]
1813 \new Staff \relative {
1816 \new Staff \relative {
1817 \set Staff.extraNatural = ##f
1824 and this turns them off in all staves:
1826 @lilypond[quote,verbatim,ragged-right]
1828 \new Staff \relative {
1831 \new Staff \relative {
1832 \set Score.extraNatural = ##f
1838 As another example, if @code{clefTransposition} is set in
1839 the @code{Score} context this immediately changes the value
1840 of the transposition in all current staves and sets a new default
1841 value which will be applied to all staves.
1843 The opposite command, @code{\unset}, effectively removes the
1844 property from the context, which causes most properties to
1845 revert to their default value. Usually @code{\unset} is not
1846 required as a new @code{\set} command will achieve what is
1849 The @code{\set} and @code{\unset} commands can appear anywhere
1850 in the input file and will take effect from the time they are
1851 encountered until the end of the score or until the property is
1852 @code{\set} or @code{\unset} again. Let's try changing the
1853 font size, which affects the size of the note heads (among
1854 other things) several times. The change is from the default
1855 value, not the most recently set value.
1857 @lilypond[quote,verbatim,ragged-right]
1860 % make note heads smaller
1863 % make note heads larger
1864 \set fontSize = #2.5
1866 % return to default size
1872 We have now seen how to set the values of several different types of
1873 property. Note that integers and numbers are always preceded by a
1874 hash sign, @code{#}, while a true or false value is specified by
1875 @code{##t} and @code{##f}, with two hash signs. A text property
1876 should be enclosed in double quotation signs, as above, although we
1877 shall see later that text can actually be specified in a much more
1878 general way by using the very powerful @code{\markup} command.
1880 @subsubheading Setting context properties with @code{\with}
1883 @cindex context properties, setting with \with
1885 The default value of context properties may be set at the time the
1886 context is created. Sometimes this is a clearer way of setting a
1887 property value if it is to remain fixed for the duration of
1888 the context. When a context is created with a @code{\new}
1889 command it may be followed immediately by a @code{\with @{ @dots{} @}}
1890 block in which the default property values are set. For example,
1891 if we wish to suppress the printing of extra naturals for the
1892 duration of a staff we would write:
1895 \new Staff \with @{ extraNatural = ##f @}
1901 @lilypond[quote,verbatim,ragged-right]
1905 gisis'4 gis aeses aes
1908 \new Staff \with { extraNatural = ##f } {
1910 gisis'4 gis aeses aes
1916 Properties set in this way may still be changed dynamically using
1917 @code{\set} and returned to the default value set in the
1918 @code{\with} block with @code{\unset}.
1920 @cindex fontSize, default and setting
1922 So if the @code{fontSize} property is set in a @code{\with} clause
1923 it sets the default value of the font size. If it is later changed
1924 with @code{\set}, this new default value may be restored with the
1925 @code{\unset fontSize} command.
1927 @subsubheading Setting context properties with @code{\context}
1929 @cindex context properties, setting with \context
1932 The values of context properties may be set in @emph{all} contexts
1933 of a particular type, such as all @code{Staff} contexts, with a single
1934 command. The context type is identified by using its
1935 type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
1936 The statement which sets the property value is the same as that in a
1937 @code{\with} block, introduced above. It is placed in a
1938 @code{\context} block within a @code{\layout} block. Each
1939 @code{\context} block will affect all contexts of the type specified
1940 throughout the @code{\score} or @code{\book} block in which the
1941 @code{\layout} block appears. Here is an example to show the format:
1943 @lilypond[verbatim,quote]
1959 If the property override is to be applied to all staves
1962 @lilypond[quote,verbatim]
1967 gisis'4 gis aeses aes
1972 gisis'4 gis aeses aes
1978 \Score extraNatural = ##f
1985 Context properties set in this way may be overridden for particular
1986 instances of contexts by statements in a @code{\with} block, and by
1987 @code{\set} commands embedded in music statements.
1992 @ruser{Changing context default settings}.
1993 @ruser{The set command}.
1995 Internals Reference:
1996 @rinternals{Contexts},
1997 @rinternals{Tunable context properties}.
2000 @node Adding and removing engravers
2001 @subsection Adding and removing engravers
2003 @cindex engravers, adding
2004 @cindex adding engravers
2005 @cindex engravers, removing
2006 @cindex removing engravers
2011 We have seen that contexts each contain several engravers, each
2012 of which is responsible for producing a particular part of the
2013 output, like bar lines, staves, note heads, stems, etc. If an
2014 engraver is removed from a context, it can no longer produce its
2015 output. This is a crude way of modifying the output, but it
2016 can sometimes be useful.
2018 @subsubheading Changing a single context
2020 To remove an engraver from a single context we use the
2021 @code{\with} command placed immediately after the context creation
2022 command, as in the previous section.
2024 As an illustration, let's repeat an example from the previous section
2025 with the staff lines removed. Remember that the staff lines are
2026 produced by the @code{Staff_symbol_engraver}.
2028 @lilypond[quote,verbatim,ragged-right]
2030 \remove "Staff_symbol_engraver"
2034 \set fontSize = #-4 % make note heads smaller
2036 \set fontSize = #2.5 % make note heads larger
2038 \unset fontSize % return to default size
2043 @cindex ambitus engraver
2045 Engravers can also be added to individual contexts.
2046 The command to do this is
2048 @code{\consists @var{Engraver_name}},
2051 placed inside a @code{\with} block. Some vocal scores have an ambitus
2052 placed at the beginning of a staff to indicate the range of notes in
2053 that staff -- see @rglos{ambitus}. The ambitus is produced by the
2054 @code{Ambitus_engraver}, which is not normally included in any
2055 context. If we add it to the @code{Voice} context, it calculates the
2056 range from that voice only:
2058 @lilypond[quote,verbatim,ragged-right]
2061 \consists "Ambitus_engraver"
2078 but if we add the ambitus engraver to the
2079 @code{Staff} context, it calculates the range from all
2080 the notes in all the voices on that staff:
2082 @lilypond[quote,verbatim,ragged-right]
2084 \consists "Ambitus_engraver"
2102 @subsubheading Changing all contexts of the same type
2106 The examples above show how to remove or add engravers to
2107 individual contexts. It is also possible to remove or add
2108 engravers to every context of a specific type by placing the
2109 commands in the appropriate context in a @code{\layout}
2110 block. For example, if we wanted to show an ambitus for every
2111 staff in a four-staff score, we could write
2113 @lilypond[quote,verbatim,ragged-right]
2142 \consists "Ambitus_engraver"
2149 The values of context properties may also be set
2150 for all contexts of a particular type by including the
2151 @code{\set} command in a @code{\context} block in the
2155 Notation Reference: @ruser{Modifying context plug-ins},
2156 @ruser{Changing context default settings}.
2159 The @code{Stem_engraver} and @code{Beam_engraver} attach their
2160 objects to note heads. If the @code{Note_heads_engraver} is removed
2161 no note heads are produced and therefore no stems or beams are created
2165 @node Extending the templates
2166 @section Extending the templates
2168 You've read the tutorial, you know how to write music, you
2169 understand the fundamental concepts. But how can you
2170 get the staves that you want? Well, you can find lots of
2171 templates (see @ref{Templates}) which may give you a start.
2172 But what if you want something that isn't covered there? Read on.
2175 * Soprano and cello::
2176 * Four-part SATB vocal score::
2177 * Building a score from scratch::
2178 * Saving typing with variables and functions::
2179 * Scores and parts::
2182 @node Soprano and cello
2183 @subsection Soprano and cello
2185 @cindex template, modifying
2186 @cindex modifying templates
2188 Start off with the template that seems closest to what you want to
2189 end up with. Let's say that you want to write something for
2190 soprano and cello. In this case, we would start with the
2191 @q{Notes and lyrics} template (for the soprano part).
2194 \version @w{"@version{}"}
2196 melody = \relative @{
2203 text = \lyricmode @{
2209 \new Voice = "one" @{
2213 \new Lyrics \lyricsto "one" \text
2220 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2223 \version @w{"@version{}"}
2225 melody = \relative @{
2239 We don't need two @code{\version} commands. We'll need the
2240 @code{melody} section. We don't want two @code{\score} sections
2241 -- if we had two @code{\score}s, we'd get the two parts separately.
2242 We want them together, as a duet. Within the @code{\score}
2243 section, we don't need two @code{\layout} or @code{\midi}.
2245 If we simply cut and paste the @code{melody} section, we would
2246 end up with two @code{melody} definitions. This would not generate
2247 an error, but the second one would be used for both melodies.
2248 So let's rename them to make them distinct. We'll call the
2249 section for the soprano @code{sopranoMusic} and the section for
2250 the cello @code{celloMusic}. While we're doing this, let's rename
2251 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2252 instances of all these names -- both the initial definition (the
2253 @code{melody = \relative @{ } part) and the name's use (in the
2254 @code{\score} section).
2256 While we're doing this, let's change the cello part's staff --
2257 celli normally use bass clef. We'll also give the cello some
2261 \version @w{"@version{}"}
2263 sopranoMusic = \relative @{
2270 sopranoLyrics = \lyricmode @{
2274 celloMusic = \relative @{
2283 \new Voice = "one" @{
2287 \new Lyrics \lyricsto "one" \sopranoLyrics
2294 This is looking promising, but the cello part won't appear in the
2295 score -- we haven't used it in the @code{\score} section. If we
2296 want the cello part to appear under the soprano part, we need to add
2299 \new Staff \celloMusic
2303 underneath the soprano stuff. We also need to add @code{<<} and
2304 @code{>>} around the music -- that tells LilyPond that there's
2305 more than one thing (in this case, two @code{Staves}) happening
2306 at once. The @code{\score} looks like this now:
2308 @c Indentation in this example is deliberately poor
2313 \new Voice = "one" @{
2317 \new Lyrics \lyricsto "one" \sopranoLyrics
2319 \new Staff \celloMusic
2327 This looks a bit messy; the indentation is messed up now. That is
2328 easily fixed. Here's the complete soprano and cello template.
2330 @lilypond[quote,verbatim,ragged-right,addversion]
2331 sopranoMusic = \relative {
2338 sopranoLyrics = \lyricmode {
2342 celloMusic = \relative {
2352 \new Voice = "one" {
2356 \new Lyrics \lyricsto "one" \sopranoLyrics
2358 \new Staff \celloMusic
2367 The starting templates can be found in the @q{Templates} appendix,
2368 see @ref{Single staff templates}.
2371 @node Four-part SATB vocal score
2372 @subsection Four-part SATB vocal score
2374 @cindex template, SATB
2375 @cindex SATB template
2377 Most vocal scores of music written for four-part mixed choir
2378 with orchestral accompaniment such as Mendelssohn's Elijah or
2379 Handel's Messiah have the choral music and words on four
2380 staves, one for each of SATB, with a piano reduction of the
2381 orchestral accompaniment underneath. Here's an example
2382 from Handel's Messiah:
2384 @c The following should appear as music without code
2385 @lilypond[quote,ragged-right]
2386 global = { \key d \major \time 4/4 }
2388 sopranoMusic = \relative {
2390 r4 d''2 a4 | d4. d8 a2 | cis4 d cis2 |
2392 sopranoWords = \lyricmode {
2393 Wor -- thy | is the lamb | that was slain |
2396 altoMusic = \relative {
2398 r4 a'2 a4 | fis4. fis8 a2 | g4 fis e2 |
2400 altoWords = \sopranoWords
2402 tenorMusic = \relative {
2404 r4 fis'2 e4 | d4. d8 d2 | e4 a, cis2 |
2406 tenorWords = \sopranoWords
2408 bassMusic = \relative {
2410 r4 d'2 cis4 | b4. b8 fis2 | e4 d a'2 |
2412 bassWords = \sopranoWords
2417 r4 <a' d fis>2 <a e' a>4 |
2418 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2419 <g cis g'>4 <a d fis> <a cis e>2 |
2425 <d, d'>4 <d d'>2 <cis cis'>4 |
2426 <b b'>4. <b' b'>8 <fis fis'>2 |
2427 <e e'>4 <d d'> <a' a'>2 |
2431 << % combine ChoirStaff and PianoStaff in parallel
2433 \new Staff = "sopranos"
2434 \with { instrumentName = #"Soprano" }
2436 \new Voice = "sopranos" {
2441 \new Lyrics \lyricsto "sopranos" {
2444 \new Staff = "altos"
2445 \with { instrumentName = #"Alto" }
2447 \new Voice = "altos" {
2452 \new Lyrics \lyricsto "altos" {
2455 \new Staff = "tenors"
2456 \with { instrumentName = #"Tenor" }
2458 \new Voice = "tenors" {
2463 \new Lyrics \lyricsto "tenors" {
2466 \new Staff = "basses"
2467 \with { instrumentName = #"Bass" }
2469 \new Voice = "basses" {
2474 \new Lyrics \lyricsto "basses" {
2478 \new PianoStaff \with { instrumentName = #"Piano" }
2480 \new Staff = "upper" \upper
2481 \new Staff = "lower" \lower
2487 @warning{This layout can be achieved very easily using the built-in
2488 template: @code{satb.ly}, see @ref{Built-in templates}. But for ease
2489 of use this template deliberately hides the necessary context
2490 structure, instead providing it automatically. So for purposes of
2491 learning let us see how to build this up from scratch. You may need
2492 to do this if the built-in template does not meet your needs
2495 The nearest copy-and-edit template to this layout is
2496 @ref{SATB vocal score and automatic piano reduction} -- but we need
2497 to change the layout and add a piano
2498 accompaniment which is not derived automatically from the vocal parts.
2499 The variables holding the music and words for the vocal parts are
2500 fine, but we shall need to add variables for the piano reduction.
2502 The order in which the contexts appear in the ChoirStaff of the
2503 template do not correspond with the order in the vocal score shown
2504 above. We need to rearrange them so there are four staves with the
2505 words written directly underneath the notes for each part. All the
2506 voices should be @code{\voiceOne}, which is the default, so the
2507 @code{\voiceXXX} commands should be removed. We also need to specify
2508 the tenor clef for the tenors. The way in which lyrics are specified
2509 in the template has not yet been encountered so we need to use the
2510 method with which we are familiar. We should also add the names of
2513 Doing this gives for our ChoirStaff:
2517 \new Staff = "sopranos"
2518 \with @{ instrumentName = #"Soprano" @}
2520 \new Voice = "sopranos" @{
2525 \new Lyrics \lyricsto "sopranos" @{
2528 \new Staff = "altos"
2529 \with @{ instrumentName = #"Alto" @}
2531 \new Voice = "altos" @{
2536 \new Lyrics \lyricsto "altos" @{
2539 \new Staff = "tenors"
2540 \with @{ instrumentName = #"Tenor" @}
2542 \new Voice = "tenors" @{
2547 \new Lyrics \lyricsto "tenors" @{
2550 \new Staff = "basses"
2551 \with @{ instrumentName = #"Bass" @}
2553 \new Voice = "basses" @{
2558 \new Lyrics \lyricsto "basses" @{
2564 Next we must work out the piano part. This is
2565 easy - we just pull out the piano part from the
2566 @q{Solo piano} template:
2569 \new PianoStaff \with @{ instrumentName = #"Piano " @}
2571 \new Staff = "upper" \upper
2572 \new Staff = "lower" \lower
2576 and add the variable definitions for @code{upper}
2579 The ChoirStaff and PianoStaff must be combined
2580 using angle brackets as we want them to be
2581 stacked one above the other:
2584 << % combine ChoirStaff and PianoStaff one above the other
2586 \new Staff = "sopranos" <<
2587 \new Voice = "sopranos" @{
2592 \new Lyrics \lyricsto "sopranos" @{
2595 \new Staff = "altos" <<
2596 \new Voice = "altos" @{
2601 \new Lyrics \lyricsto "altos" @{
2604 \new Staff = "tenors" <<
2605 \clef "G_8" % tenor clef
2606 \new Voice = "tenors" @{
2611 \new Lyrics \lyricsto "tenors" @{
2614 \new Staff = "basses" <<
2616 \new Voice = "basses" @{
2621 \new Lyrics \lyricsto "basses" @{
2626 \new PianoStaff \with @{ instrumentName = #"Piano" @}
2628 \new Staff = "upper" \upper
2629 \new Staff = "lower" \lower
2634 Combining all these together and adding the music
2635 for the three bars of the example above gives:
2637 @lilypond[quote,verbatim,ragged-right,addversion]
2638 global = { \key d \major \time 4/4 }
2639 sopranoMusic = \relative {
2641 r4 d''2 a4 | d4. d8 a2 | cis4 d cis2 |
2643 sopranoWords = \lyricmode {
2644 Wor -- thy | is the lamb | that was slain |
2646 altoMusic = \relative {
2648 r4 a'2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2650 altoWords = \sopranoWords
2651 tenorMusic = \relative {
2653 r4 fis'2 e4 | d4. d8 d2 | e4 a, cis2 |
2655 tenorWords = \sopranoWords
2656 bassMusic = \relative {
2658 r4 d'2 cis4 | b4. b8 fis2 | e4 d a'2 |
2660 bassWords = \sopranoWords
2664 r4 <a' d fis>2 <a e' a>4 |
2665 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2666 <g cis g'>4 <a d fis> <a cis e>2 |
2671 <d, d'>4 <d d'>2 <cis cis'>4 |
2672 <b b'>4. <b' b'>8 <fis fis'>2 |
2673 <e e'>4 <d d'> <a' a'>2 |
2677 << % combine ChoirStaff and PianoStaff in parallel
2679 \new Staff = "sopranos"
2680 \with { instrumentName = #"Soprano" }
2682 \new Voice = "sopranos" {
2687 \new Lyrics \lyricsto "sopranos" {
2690 \new Staff = "altos"
2691 \with { instrumentName = #"Alto" }
2693 \new Voice = "altos" {
2698 \new Lyrics \lyricsto "altos" {
2701 \new Staff = "tenors"
2702 \with { instrumentName = #"Tenor" }
2704 \new Voice = "tenors" {
2709 \new Lyrics \lyricsto "tenors" {
2712 \new Staff = "basses"
2713 \with { instrumentName = #"Bass" }
2715 \new Voice = "basses" {
2720 \new Lyrics \lyricsto "basses" {
2726 \with { instrumentName = #"Piano " }
2728 \new Staff = "upper" \upper
2729 \new Staff = "lower" \lower
2736 @node Building a score from scratch
2737 @subsection Building a score from scratch
2739 @cindex template, writing your own
2740 @cindex example of writing a score
2741 @cindex writing a score, example
2742 @cindex score, example of writing
2744 After gaining some facility with writing LilyPond code, you
2745 may find that it is easier to build a score from scratch
2746 rather than modifying one of the templates. You can also
2747 develop your own style this way to suit the sort of music you
2748 like. Let's see how to put together the score for an organ
2749 prelude as an example.
2751 We begin with a header section. Here go the title, name
2752 of composer, etc, then come any variable definitions, and
2753 finally the score block. Let's start with these in outline
2754 and fill in the details later.
2756 We'll use the first two bars of Bach's prelude
2757 based on @emph{Jesu, meine Freude} which is written for two
2758 manuals and pedal organ. You can see these two bars of music
2759 at the bottom of this section. The top manual part has two voices,
2760 the lower and pedal organ one each. So we need four
2761 music definitions and one to define the time signature
2765 \version @w{"@version{}"}
2767 title = "Jesu, meine Freude"
2768 composer = "J S Bach"
2770 keyTime = @{ \key c \minor \time 4/4 @}
2771 ManualOneVoiceOneMusic = @{ s1 @}
2772 ManualOneVoiceTwoMusic = @{ s1 @}
2773 ManualTwoMusic = @{ s1 @}
2774 PedalOrganMusic = @{ s1 @}
2780 For now we've just used a spacer note, @code{s1},
2781 instead of the real music. We'll add that later.
2783 Next let's see what should go in the score block.
2784 We simply mirror the staff structure we want.
2785 Organ music is usually written on three staves,
2786 one for each manual and one for the pedals. The
2787 manual staves should be bracketed together, so we
2788 need to use a PianoStaff for them. The first
2789 manual part needs two voices and the second manual
2794 \new Staff = "ManualOne" <<
2796 \ManualOneVoiceOneMusic
2799 \ManualOneVoiceTwoMusic
2801 >> % end ManualOne Staff context
2802 \new Staff = "ManualTwo" <<
2806 >> % end ManualTwo Staff context
2807 >> % end PianoStaff context
2810 Next we need to add a staff for the pedal organ.
2811 This goes underneath the PianoStaff, but it must
2812 be simultaneous with it, so we need angle brackets
2813 around the two. Missing these out would generate
2814 an error in the log file. It's a common mistake
2815 which you'll make sooner or later! Try copying
2816 the final example at the end of this section,
2817 remove these angle brackets, and compile it to
2818 see what errors it generates.
2821 << % PianoStaff and Pedal Staff must be simultaneous
2823 \new Staff = "ManualOne" <<
2825 \ManualOneVoiceOneMusic
2828 \ManualOneVoiceTwoMusic
2830 >> % end ManualOne Staff context
2831 \new Staff = "ManualTwo" <<
2835 >> % end ManualTwo Staff context
2836 >> % end PianoStaff context
2837 \new Staff = "PedalOrgan" <<
2845 It is not necessary to use the simultaneous construct
2846 @code{<< @dots{} >>} for the manual two staff and the pedal organ staff,
2847 since they contain only one music expression, but it does no harm,
2848 and always using angle brackets after @code{\new Staff} is a good
2849 habit to cultivate in case there are multiple voices. The opposite
2850 is true for Voices: these should habitually be followed by braces
2851 @code{@{ @dots{} @}} in case your music is coded in several variables
2852 which need to run consecutively.
2854 Let's add this structure to the score block, and adjust the indenting.
2855 We also add the appropriate clefs, ensure stems, ties and slurs in
2856 each voice on the upper staff point to the right direction with
2857 @code{\voiceOne} and @code{\voiceTwo}, and enter the key and time
2858 signature to each staff using our predefined variable, @code{\keyTime}.
2862 << % PianoStaff and Pedal Staff must be simultaneous
2864 \new Staff = "ManualOne" <<
2865 \keyTime % set key and time signature
2869 \ManualOneVoiceOneMusic
2873 \ManualOneVoiceTwoMusic
2875 >> % end ManualOne Staff context
2876 \new Staff = "ManualTwo" <<
2882 >> % end ManualTwo Staff context
2883 >> % end PianoStaff context
2884 \new Staff = "PedalOrgan" <<
2890 >> % end PedalOrgan Staff
2892 @} % end Score context
2895 @cindex stretchability of staves
2896 @cindex staves, stretchability
2898 The above layout of the organ staves is almost perfect; however,
2899 there is a slight defect which is not visible by looking at just a
2900 single system: The distance of the pedal staff to the left hand staff
2901 should behave approximately the same as the right hand staff to the
2902 left hand staff. In particular, the stretchability of staves in a
2903 @code{PianoStaff} context is limited (so that the distance between
2904 the staves for the left and right hand can't become too large), and
2905 the pedal staff should behave similarly.
2907 @cindex sub-properties
2908 @cindex properties, sub-properties
2909 @cindex graphical objects
2910 @cindex objects, graphical
2913 Stretchability of staves can be controlled with the
2914 @code{staff-staff-spacing} property of the
2915 @code{VerticalAxisGroup} @q{graphical object} (commonly called
2916 @q{grob}s within the lilypond documentation) -- don't worry about
2917 the details right now; this is fully explained later. For the
2918 curious, have a look at @ruser{Overview of modifying properties}.
2919 In this case, we want to modify the @code{stretchability}
2920 sub-property only. Again, for the curious, you can find the
2921 default values for the staff-staff-spacing property
2922 in file @file{scm/define-grobs.scm} by looking up the definition
2923 of the @code{VerticalAxisGroup} grob. The value for
2924 @code{stretchability} is taken from the definition of the
2925 @code{PianoStaff} context (in file @file{ly/engraver-init.ly})
2926 so that the values are identical.
2930 << % PianoStaff and Pedal Staff must be simultaneous
2932 \new Staff = "ManualOne" <<
2933 \keyTime % set key and time signature
2937 \ManualOneVoiceOneMusic
2941 \ManualOneVoiceTwoMusic
2943 >> % end ManualOne Staff context
2944 \new Staff = "ManualTwo" \with @{
2945 \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
2952 >> % end ManualTwo Staff context
2953 >> % end PianoStaff context
2954 \new Staff = "PedalOrgan" <<
2960 >> % end PedalOrgan Staff
2962 @} % end Score context
2964 That completes the structure. Any three-staff organ music
2965 will have a similar structure, although the number of voices
2966 may vary. All that remains now
2967 is to add the music, and combine all the parts together.
2969 @lilypond[quote,verbatim,ragged-right,addversion]
2971 title = "Jesu, meine Freude"
2972 composer = "J S Bach"
2974 keyTime = { \key c \minor \time 4/4 }
2975 ManualOneVoiceOneMusic = \relative {
2979 ManualOneVoiceTwoMusic = \relative {
2980 ees'16 d ees8~ 16 f ees d c8 d~ d c~ |
2981 8 c4 b8 c8. g16 c b c d |
2983 ManualTwoMusic = \relative {
2984 c'16 b c8~ 16 b c g a8 g~ 16 g aes ees |
2985 f16 ees f d g aes g f ees d ees8~ 16 f ees d |
2987 PedalOrganMusic = \relative {
2988 r8 c16 d ees d ees8~ 16 a, b g c b c8 |
2989 r16 g ees f g f g8 c,2 |
2993 << % PianoStaff and Pedal Staff must be simultaneous
2995 \new Staff = "ManualOne" <<
2996 \keyTime % set key and time signature
3000 \ManualOneVoiceOneMusic
3004 \ManualOneVoiceTwoMusic
3006 >> % end ManualOne Staff context
3007 \new Staff = "ManualTwo" \with {
3008 \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
3015 >> % end ManualTwo Staff context
3016 >> % end PianoStaff context
3017 \new Staff = "PedalOrgan" <<
3023 >> % end PedalOrgan Staff context
3025 } % end Score context
3032 @node Saving typing with variables and functions
3033 @subsection Saving typing with variables and functions
3038 By this point, you've seen this kind of thing:
3040 @lilypond[quote,verbatim,ragged-right]
3041 hornNotes = \relative { c''4 b dis c }
3050 You may even realize that this could be useful in minimalist music:
3052 @lilypond[quote,verbatim,ragged-right]
3053 fragmentA = \relative { a'4 a8. b16 }
3054 fragmentB = \relative { a'8. gis16 ees4 }
3056 violin = \new Staff {
3057 \fragmentA \fragmentA |
3058 \fragmentB \fragmentA |
3068 However, you can also use these variables (also known as
3069 macros, or user-defined commands) for tweaks:
3071 @lilypond[quote,verbatim,ragged-right]
3072 dolce = \markup { \italic \bold dolce }
3074 centreText = { \once \override TextScript.self-alignment-X = #CENTER }
3077 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
3080 violin = \relative {
3082 c''4._\dolce b8 a8 g a b |
3084 c4.^"hi there!" d8 e f g d |
3085 c4.\fthenp b8 c4 c-. |
3096 These variables are obviously useful for saving
3097 typing. But they're worth considering even if you
3098 only use them once -- they reduce complexity. Let's
3099 look at the previous example without any
3100 variables. It's a lot harder to read, especially
3104 violin = \relative @{
3106 c''4._\markup @{ \italic \bold dolce @} b8 a8 g a b |
3107 \once \override TextScript.self-alignment-X = #CENTER
3108 c4.^"hi there!" d8 e f g d |
3110 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p
3117 So far we've seen static substitution -- when LilyPond
3118 sees @code{\centreText}, it replaces it with the stuff that
3119 we've defined it to be (ie the stuff to the right of
3120 @code{centreText=}).
3122 LilyPond can handle non-static substitution, too (you
3123 can think of these as functions).
3125 @lilypond[quote,verbatim,ragged-right]
3127 #(define-music-function
3131 \once \override TextScript.padding = #padding
3135 c''4^"piu mosso" b a b
3137 c4^"piu mosso" b a b
3139 c4^"piu mosso" b a b
3143 Using variables is also a good way to reduce work if the
3144 LilyPond input syntax changes (see
3145 @rprogram{Updating files with convert-ly}). If
3146 you have a single definition (such as @code{\dolce}) for all your
3147 input files (see @ref{Style sheets}), then if the syntax changes, you
3148 only need to update your single @code{\dolce} definition,
3149 instead of making changes throughout every @file{.ly} file.
3152 @node Scores and parts
3153 @subsection Scores and parts
3155 In orchestral music, all notes are printed twice. Once in a part for
3156 the musicians, and once in a full score for the conductor. Variables can
3157 be used to avoid double work. The music is entered once, and stored in
3158 a variable. The contents of that variable is then used to generate
3159 both the part and the full score.
3161 It is convenient to define the notes in a special file. For example,
3162 suppose that the file @file{horn-music.ly} contains the following part
3163 of a horn/@/bassoon duo
3166 hornNotes = \relative @{
3168 r4 f8 a | cis4 f | e4 d |
3173 Then, an individual part is made by putting the following in a file
3176 \include "horn-music.ly"
3179 instrument = "Horn in F"
3183 \transpose f c' \hornNotes
3190 \include "horn-music.ly"
3194 substitutes the contents of @file{horn-music.ly} at this position in
3195 the file, so @code{hornNotes} is defined afterwards. The command
3196 @code{\transpose f@tie{}c'} indicates that the argument, being
3197 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
3198 @code{f} is denoted by notated @code{c'}, which corresponds with the
3199 tuning of a normal French Horn in@tie{}F. The transposition can be seen
3200 in the following output
3202 @lilypond[quote,ragged-right]
3203 \transpose f c' \relative {
3205 r4 f8 a | cis4 f | e4 d |
3209 In ensemble pieces, one of the voices often does not play for many
3210 measures. This is denoted by a special rest, the multi-measure
3211 rest. It is entered with a capital @code{R} followed by a duration
3212 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
3213 etc.). By multiplying the
3214 duration, longer rests can be constructed. For example, this rest
3215 takes 3@tie{}measures in 2/4 time
3221 When printing the part, multi-measure rests must be compressed. There
3222 is a music function available to do this:
3225 \compressMMRests @{ ... @}
3228 Applying this to @code{hornNotes} gives:
3230 @lilypond[quote,ragged-right]
3231 \compressMMRests \transpose f c' \relative {
3234 r4 f8 a | cis4 f | e4 d |
3239 The score is made by combining all of the music together. Assuming
3240 that the other voice is in @code{bassoonNotes} in the file
3241 @file{bassoon-music.ly}, a score is made with
3244 \include "bassoon-music.ly"
3245 \include "horn-music.ly"
3248 \new Staff \hornNotes
3249 \new Staff \bassoonNotes
3256 @lilypond[quote,ragged-right]
3262 r4 f8 a | cis4 f | e4 d |
3267 r4 d,8 f | gis4 c | b4 bes |
3268 a8 e f4 | g4 d | gis4 f |
3275 @ref{Organizing pieces with variables}.
3279 @ruser{Writing parts},
3280 @ruser{Full measure rests},
3281 @ruser{Including LilyPond files}.