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.
77 Up to this point none of the examples you have seen have used a
78 @code{\score@{@}} command. This is because LilyPond automatically
79 adds the extra commands which are needed when you give it simple
80 input. LilyPond treats input like this:
89 as shorthand for this:
106 In other words, if the input contains a single music expression,
107 LilyPond will interpret the file as though the music expression
108 was wrapped up inside the commands shown above.
110 @cindex implicit contexts
111 @cindex contexts, implicit
113 @strong{A word of warning!} Many of the examples in the LilyPond
114 documentation will omit the @code{\new Staff} and @code{\new Voice}
115 commands, leaving them to be created implicitly. For simple
116 examples this works well, but for more complex examples, especially
117 when additional commands are used, the implicit creation of contexts
118 can give surprising results, maybe creating extra unwanted staves.
119 The way to create contexts explicitly is explained in
120 @ref{Contexts and engravers}.
122 @warning{When entering more than a few lines of music it is
123 advisable to always create staves and voices explicitly.}
125 For now, though, let us return to the first example and examine the
126 @code{\score} command, leaving the others to default.
128 A @code{\score} block must always contain exactly one music
129 expression. Remember that a music expression could be anything
130 from a single note to a huge compound expression like
135 @var{ @dots{} insert the whole score of a Wagner opera in here @dots{} }
141 Since everything is inside @code{@{ @dots{} @}}, it counts
142 as one music expression.
144 As we saw previously, the @code{\score} block can contain other
167 Note that these three commands -- @code{\header}, @code{\layout} and
168 @code{\midi} -- are special: unlike many other commands which begin
169 with a backward slash (@code{\}) they are @emph{not} music expressions
170 and are not part of any music expression. So they may be placed
171 inside a @code{\score} block or outside it. In fact, these commands
172 are commonly placed outside the @code{\score} block -- for example,
173 @code{\header} is often placed above the @code{\score} command, as the
174 example at the beginning of this section shows.
176 Two more commands you have not previously seen are
177 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
178 shown they will cause LilyPond to produce a printed output and a
179 MIDI output respectively. They are described fully in the
180 Notation Reference -- @ruser{Score layout}, and
181 @ruser{Creating MIDI files}.
183 @cindex scores, multiple
184 @cindex book block, implicit
185 @cindex implicit book block
189 You may code multiple @code{\score} blocks. Each will be
190 treated as a separate score, but they will be all combined into
191 a single output file. A @code{\book} command is not necessary
192 -- one will be implicitly created. However, if you would like
193 separate output files from one @file{.ly} file then the
194 @code{\book} command should be used to separate the different
195 sections: each @code{\book} block will produce a
196 separate output file.
200 Every @code{\book} block creates a separate output file (e.g., a
201 PDF file). If you haven't explicitly added one, LilyPond wraps
202 your entire input code in a @code{\book} block implicitly.
204 Every @code{\score} block is a separate chunk of music within a
207 @cindex layout block, effect of location
209 Every @code{\layout} block affects the @code{\score} or
210 @code{\book} block in which it appears -- i.e., a @code{\layout}
211 block inside a @code{\score} block affects only that @code{\score}
212 block, but a @code{\layout} block outside of a @code{\score} block
213 (and thus in a @code{\book} block, either explicitly or
214 implicitly) will affect every @code{\score} in that @code{\book}.
216 For details see @ruser{Multiple scores in a book}.
220 Another great shorthand is the ability to define variables, as
221 shown in @ref{Organizing pieces with variables}. All the
225 melody = \relative c' @{
234 When LilyPond looks at this file, it takes the value of
235 @code{melody} (everything after the equals sign) and inserts it
236 whenever it sees @code{\melody}. There's nothing special about
237 the name -- it could be @code{melody}, @code{global},
238 @code{keyTime}, @code{pianorighthand}, or something else.
239 Remember that you can use almost any name you like as long as it
240 contains just alphabetic characters and is distinct from LilyPond
241 command names. For more details, see @ref{Saving typing with
242 variables and functions}. The exact limitations on variable names
243 are detailed in @ruser{File structure}.
247 For a complete definition of the input format, see
248 @ruser{File structure}.
251 @node Score is a (single) compound musical expression
252 @subsection Score is a (single) compound musical expression
257 @cindex contents of a score block
258 @cindex score block, contents of
259 @cindex compound music expression
260 @cindex music expression, compound
262 We saw the general organization of LilyPond input files in the
263 previous section, @ref{Introduction to the LilyPond file structure}.
264 But we seemed to skip over the most important part: how do we figure
265 out what to write after @code{\score}?
267 We didn't skip over it at all. The big mystery is simply that
268 there @emph{is} no mystery. This line explains it all:
271 @emph{A @code{\score} block must contain exactly one music expression.}
275 To understand what is meant by a
276 music expression, you may find it useful to review the tutorial,
277 @ref{Music expressions explained}. In that section, we saw how to
278 build big music expressions from small pieces -- we started from
279 notes, then chords, etc. Now we're going to start from a big
280 music expression and work our way down. For simplicity, we'll use
281 just a singer and piano in our example. We don't need a
282 @code{StaffGroup} for this ensemble, which simply groups a number
283 of staves together with a bracket at the left, but we do need
284 staves for a singer and a piano, though.
289 \new Staff = "singer" <<
291 \new PianoStaff = "piano" <<
298 Here we have given names to the staves -- @qq{singer} and
299 @qq{piano}. This is not essential here, but it is a useful habit
300 to cultivate so that you can see at a glance what each stave is
303 Remember that we use @code{<< @dots{} >>} instead of @code{@{ @dots{} @}} to
304 show simultaneous music. This causes the vocal part and piano part
305 to appear one above the other in the score. The @code{<< @dots{} >>}
306 construct would not be necessary for the Singer staff in the example
307 above if it were going to contain only one sequential music
308 expression, but @code{<< @dots{} >>} rather than braces is necessary if
309 the music in the Staff is to contain two or more simultaneous
310 expressions, e.g. two simultaneous Voices, or a Voice with lyrics.
311 We're going to have a voice with lyrics, so angle brackets are
312 required. We'll add some real music later; for now let's just put
313 in some dummy notes and lyrics. If you've forgotten how to add lyrics
314 you may wish to review @code{\addlyrics} in @ref{Setting simple songs}.
316 @lilypond[verbatim,quote,ragged-right]
319 \new Staff = "singer" <<
320 \new Voice = "vocal" { c'1 }
323 \new PianoStaff = "piano" <<
324 \new Staff = "upper" { c'1 }
325 \new Staff = "lower" { c'1 }
332 Now we have a lot more details. We have the singer's staff: it
333 contains a @code{Voice} (in LilyPond, this term refers to a set of
334 notes, not necessarily vocal notes -- for example, a violin
335 generally plays one voice) and some lyrics. We also have a piano
336 staff: it contains an upper staff (right hand) and a lower staff
337 (left hand), although the lower staff has yet to be given a bass
340 At this stage, we could start filling in notes. Inside the curly
341 braces next to @code{\new Voice = "vocal"}, we could start writing
349 But if we did that, the @code{\score} section would get pretty
350 long, and it would be harder to understand what was happening. So
351 let's use variables instead. These were introduced at the end
352 of the previous section, remember? To ensure the contents of the
353 @code{text} variable are interpreted as lyrics we preface them with
354 @code{\lyricmode}. Like @code{\addlyrics}, this switches the input
355 mode to lyrics. Without that, LilyPond would try to interpret the
356 contents as notes, which would generate errors. (Several other
357 input modes are available, see @ruser{Input modes}.)
359 So, adding a few notes and a bass clef for the left hand, we now
360 have a piece of real music:
362 @lilypond[verbatim,quote,ragged-right]
363 melody = \relative c'' { r4 d8\noBeam g, c4 r }
364 text = \lyricmode { And God said, }
365 upper = \relative c'' { <g d g,>2~ <g d g,> }
366 lower = \relative c { b2 e }
370 \new Staff = "singer" <<
371 \new Voice = "vocal" { \melody }
374 \new PianoStaff = "piano" <<
375 \new Staff = "upper" { \upper }
376 \new Staff = "lower" {
386 When writing (or reading) a @code{\score} section, just take it
387 slowly and carefully. Start with the outer level, then work on
388 each smaller level. It also really helps to be strict with
389 indentation -- make sure that each item on the same level starts
390 on the same horizontal position in your text editor.
394 Notation Reference: @ruser{Structure of a score}.
397 @node Nesting music expressions
398 @subsection Nesting music expressions
400 @cindex staves, temporary
401 @cindex temporary staves
404 It is not essential to declare all staves at the beginning; they may
405 be introduced temporarily at any point. This is particularly useful
406 for creating ossia sections -- see @rglos{ossia}. Here is a simple
407 example showing how to introduce a new staff temporarily for the
408 duration of three notes:
410 @lilypond[verbatim,quote,ragged-right]
427 Note that the size of the clef is the same as a clef printed
428 following a clef change -- slightly smaller than the clef
429 at the beginning of the line. This is usual for clefs printed
430 in the middle of a line.
432 @cindex staff, positioning
434 The ossia section may be placed above the staff
437 @lilypond[verbatim,quote,ragged-right]
438 \new Staff = "main" {
445 alignAboveContext = #"main"
453 This example uses @code{\with}, which will be explained more
454 fully later. It is a means of modifying the default behavior
455 of a single Staff. Here it says that the new staff should be
456 placed above the staff called @qq{main} instead of the default
457 position which is below.
461 Ossia are often written without clef and without
462 time signature and are usually in a smaller font.
463 These require further commands which
464 have not yet been introduced. See @ref{Size of objects},
465 and @ruser{Ossia staves}.
468 @node On the un-nestedness of brackets and ties
469 @subsection On the un-nestedness of brackets and ties
471 @cindex brackets, nesting
472 @cindex bracket types
473 @cindex brackets, enclosing vs. marking
475 You have already met a number of different types of bracket and
476 bracket-like constructs in writing the input file to LilyPond.
477 These obey different rules which can be confusing at first.
478 Let's first review the different types of brackets and bracket-like
481 @c attempt to force this onto a new page
483 @multitable @columnfractions .3 .7
484 @headitem Bracket Type
486 @item @code{@{ @dots{} @}}
487 @tab Encloses a sequential segment of music
488 @item @code{< @dots{} >}
489 @tab Encloses the notes of a chord
490 @item @code{<< @dots{} >>}
491 @tab Encloses simultaneous music expressions
492 @item @code{( @dots{} )}
493 @tab Marks the start and end of a slur
494 @item @code{\( @dots{} \)}
495 @tab Marks the start and end of a phrasing slur
496 @item @code{[ @dots{} ]}
497 @tab Marks the start and end of a manual beam
500 To these we should add other constructs which generate lines
501 between or across notes: ties (marked by a tilde, @code{~}),
502 tuplets written as @code{\tuplet x/y @{ @dots{} @}}, and grace notes
503 written as @code{\grace @{ @dots{} @}}.
505 Outside LilyPond, the conventional use of brackets requires the
506 different types to be properly nested, like this, @code{<< [ @{ ( @dots{} )
507 @} ] >>}, with the closing brackets being encountered in exactly the
508 opposite order to the opening brackets. This @strong{is} a
509 requirement for the three types of bracket described by the word
510 @q{Encloses} in the table above -- they must nest properly. However,
511 the remaining bracket-like constructs, described with the word
512 @q{Marks} in the table above together with ties and tuplets, do
513 @strong{not} have to nest properly with any of the brackets or
514 bracket-like constructs. In fact, these are not brackets in
515 the sense that they enclose something -- they are simply markers to
516 indicate where something starts and ends.
518 So, for example, a phrasing slur can start before a manually
519 inserted beam and end before the end of the beam -- not very
520 musical, perhaps, but possible:
522 @lilypond[quote,verbatim,ragged-right,relative=2]
523 g8\( a b[ c b\) a] g4
526 In general, different kinds of brackets, bracket-like constructs,
527 and those implied by tuplets, ties and grace notes, may be mixed
528 freely. This example shows a beam extending into a tuplet (line 1),
529 a slur extending into a tuplet (line 2), a beam and a slur
530 extending into a tuplet, a tie crossing two tuplets, and a
531 phrasing slur extending out of a tuplet (lines 3 and 4).
533 @lilypond[quote,verbatim,ragged-right,relative=1]
534 r16[ g \tuplet 3/2 { r16 e'8] }
535 g,16( a \tuplet 3/2 { b16 d) e }
536 g,8[( a \tuplet 3/2 { b8 d) e~] } |
537 \tuplet 5/4 { e32\( a, b d e } a4.\)
541 @node Voices contain music
542 @section Voices contain music
544 Singers need voices to sing, and so does LilyPond.
545 The actual music for all instruments in a score
546 is contained in Voices -- the most fundamental
547 of all LilyPond's concepts.
550 * I'm hearing Voices::
551 * Explicitly instantiating voices::
552 * Voices and vocals::
555 @node I'm hearing Voices
556 @subsection I'm hearing Voices
560 @cindex multiple voices
561 @cindex voices, multiple
562 @cindex Voice context
563 @cindex context, Voice
564 @cindex simultaneous music
565 @cindex music, simultaneous
566 @cindex concurrent music
567 @cindex music, concurrent
568 @cindex voices vs. chords
569 @cindex chords vs. voices
571 The lowest, most fundamental or innermost layers in a LilyPond
572 score are called @q{Voice contexts} or just @q{Voices} for short.
573 Voices are sometimes called @q{layers} in other notation
576 In fact, a Voice layer or context is the only one which can contain
577 music. If a Voice context is not explicitly declared one is created
578 automatically, as we saw at the beginning of this chapter. Some
579 instruments such as an Oboe can play only one note at a time. Music
580 written for such instruments requires just a single voice. Instruments
581 which can play more than one note at a time like the piano will often
582 require multiple voices to encode the different concurrent notes and
583 rhythms they are capable of playing.
585 A single voice can contain many notes in a chord, of course,
586 so when exactly are multiple voices needed? Look first at
587 this example of four chords:
589 @lilypond[quote,verbatim,ragged-right,relative=1]
591 <d g>4 <d fis> <d a'> <d g>
594 This can be expressed using just the single angle bracket chord
595 symbols, @code{< @dots{} >}, and for this just a single voice is
596 needed. But suppose the F-sharp were actually an eighth-note
597 followed by an eighth-note G, a passing note on the way to the A?
598 Now we have two notes which start at the same time but have
599 different durations: the quarter-note D and the eighth-note
600 F-sharp. How are these to be coded? They cannot be written as
601 a chord because all the notes in a chord must have the same
602 duration. And they cannot be written as two sequential notes
603 as they need to start at the same time. This is when two
606 Let us see how this is done in LilyPond input syntax.
611 The easiest way to enter fragments with more than one voice on a
612 staff is to enter each voice as a sequence (with @code{@{ @dots{} @}}),
613 and combine them simultaneously with angle brackets, @code{<< @dots{} >>}.
614 The fragments must also be separated with double backward slashes,
615 @code{\\}, to place them in separate voices. Without these, the
616 notes would be entered into a single voice, which would usually
617 cause errors. This technique is particularly suited to pieces of
618 music which are largely homophonic with occasional short sections
621 Here's how we split the chords above into two voices and add both
622 the passing note and a slur:
624 @lilypond[quote,verbatim,ragged-right,relative=2]
626 % Voice "1" Voice "2"
627 << { g4 fis8( g) a4 g } \\ { d4 d d d } >>
630 Notice how the stems of the second voice now point down.
632 Here's another simple example:
634 @lilypond[quote,verbatim,ragged-right,relative=2]
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 } >> |
642 It is not necessary to use a separate @code{<< \\ >>} construct
643 for each bar. For music with few notes in each bar this layout
644 can help the legibility of the code, but if there are many
645 notes in each bar it may be better to split out each voice
646 separately, like this:
648 @lilypond[quote,verbatim,ragged-right,relative=2]
664 @cindex voices, naming
665 @cindex voices crossing brackets
666 @cindex slurs crossing brackets
667 @cindex ties crossing brackets
669 This example has just two voices, but the same construct may be
670 used to encode three or more voices by adding more back-slash
673 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
674 The first contexts set the @emph{outer} voices, the highest
675 voice in context @code{"1"} and the lowest voice in context
676 @code{"2"}. The inner voices go in contexts @code{"3"} and
677 @code{"4"}. In each of these contexts, the vertical direction
678 of slurs, stems, ties, dynamics etc., is set appropriately.
680 @lilypond[quote,verbatim]
681 \new Staff \relative c' {
684 % Voice "1" Voice "2" Voice "3"
685 << { g4 f e } \\ { r8 e4 d c8~ } >> |
686 << { d2 e } \\ { c8 b16 a b8 g~ 2 } \\ { s4 b c2 } >> |
690 These voices are all separate from the main voice that contains
691 the notes just outside the @code{<< @dots{} >>} construct. Let's call
692 this the @emph{simultaneous construct}. Slurs and ties may only
693 connect notes within the same voice, so slurs and ties cannot go
694 into or out of a simultaneous construct. Conversely,
695 parallel voices from separate simultaneous constructs on the same
696 staff are the same voice. Other voice-related properties also
697 carry across simultaneous constructs. Here is the same example,
698 with different colors and note heads for each voice. Note that
699 changes in one voice do not affect other voices, but they do
700 persist in the same voice later. Note also that tied notes may be
701 split across the same voices in two constructs, shown here in the
704 @lilypond[quote,verbatim]
705 \new Staff \relative c' {
734 @funindex \voiceOneStyle
735 @funindex \voiceTwoStyle
736 @funindex \voiceThreeStyle
737 @funindex \voiceFourStyle
738 @funindex \voiceNeutralStyle
740 The commands @code{\voiceXXXStyle} are mainly intended for use in
741 educational documents such as this one. They modify the color
742 of the note head, the stem and the beams, and the style of the
743 note head, so that the voices may be easily distinguished.
744 Voice one is set to red diamonds, voice two to blue triangles,
745 voice three to green crossed circles, and voice four (not used
746 here) to magenta crosses; @code{\voiceNeutralStyle} (also not
747 used here) reverts the style back to the default.
748 We shall see later how commands like these may be created by the
750 See @ref{Visibility and color of objects} and
751 @ref{Using variables for layout adjustments}.
753 @cindex polyphony and relative note entry
754 @cindex relative note entry and polyphony
756 Polyphony does not change the relationship of notes within a
757 @code{\relative} block. Each note is still calculated relative to
758 the note immediately preceding it, or to the first note of the
759 preceding chord. So in
762 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
766 @code{noteB} is relative to @code{noteA} @*
767 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
768 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
770 @code{noteE} is relative to @code{noteD}, not @code{noteA}.
772 An alternative way, which may be clearer if the notes in the
773 voices are widely separated, is to place a @code{\relative}
774 command at the start of each voice:
777 \relative c' @{ noteA @dots{} @}
779 \relative c'' @{ < noteB noteC > @dots{} @}
781 \relative g' @{ noteD @dots{} @}
783 \relative c' @{ noteE @dots{} @}
786 Let us finally analyze the voices in a more complex piece of music.
787 Here are the notes from the first two bars of the second of Chopin's
788 Deux Nocturnes, Op 32. This example will be used at later stages in
789 this and the next chapter to illustrate several techniques for
790 producing notation, so please ignore for now anything in the
791 underlying code which looks mysterious and concentrate just on the
792 music and the voices -- the complications will all be explained in
795 @c The following should appear as music without code
796 @lilypond[quote,ragged-right]
797 \new Staff \relative c'' {
803 % Ignore these for now - they are explained in Ch 4
804 \once \override NoteColumn.ignore-collision = ##t
806 \once \override NoteColumn.force-hshift = #0.5
812 \override NoteColumn.force-hshift = #0
820 The direction of the stems is often used to indicate the continuity of
821 two simultaneous melodic lines. Here the stems of the highest notes
822 are all pointing up and the stems of the lower notes are all pointing
823 down. This is the first indication that more than one voice is
826 But the real need for multiple voices arises when notes
827 which start at the same time have different durations.
828 Look at the notes which start at beat three in the first
829 bar. The A-flat is a dotted quarter note, the F is a
830 quarter note and the D-flat is a half note. These
831 cannot be written as a chord as all the notes in a chord
832 must have the same duration. Neither can they be written
833 as sequential notes, as they must start at the same time.
834 This section of the bar requires three voices, and the
835 normal practice would be to write the whole bar as three
836 voices, as shown below, where we have used different note heads
837 and colors for the three voices. Again, the code behind this
838 example will be explained later, so ignore anything you do
841 @c The following should appear as music without code
842 @c The three voice styles should be defined in -init
843 @lilypond[quote,ragged-right]
844 \new Staff \relative c'' {
853 % Ignore these for now - they are explained in Ch 4
854 \once \override NoteColumn.ignore-collision = ##t
856 \once \override NoteColumn.force-hshift = #0.5
859 \\ % No Voice three (we want stems down)
862 \override NoteColumn.force-hshift = #0
871 Let us try to encode this music from scratch. As we
872 shall see, this encounters some difficulties. We begin as
873 we have learnt, using the @code{<< \\ >>} construct to
874 enter the music of the first bar in three voices:
876 @lilypond[quote,verbatim,ragged-right]
877 \new Staff \relative c'' {
880 { c2 aes4. bes8 } \\ { <ees, c>2 des } \\ { aes'2 f4 fes }
887 @cindex voices and stem directions
888 @cindex stem directions and voices
891 The stem directions are automatically assigned with the
892 odd-numbered voices taking upward stems and the even-numbered
893 voices downward ones. The stems for voices 1 and 2 are right,
894 but the stems in voice 3 should go down in this particular piece
895 of music. We can correct this by skipping voice three
896 and placing the music in voice four. This is done by simply
897 adding another pair of @code{\\}.
899 @lilypond[quote,verbatim,ragged-right]
900 \new Staff \relative c'' {
906 \\ % Omit Voice three
915 We see that this fixes the stem direction, but the horizontal
916 placement of notes is not what we want. LilyPond shifts the
917 inner notes when they or their stems would collide with outer
918 voices, but this is not appropriate for piano music. In other
919 situations, the shifts LilyPond applies might fail to clear
920 the collisions. LilyPond provides several ways to adjust the
921 horizontal placing of notes. We are not quite ready yet to see
922 how to correct this, so we shall leave this problem until a
923 later section --- see the @code{force-hshift} property in
924 @ref{Fixing overlapping notation}.
926 @warning{Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be
927 created @q{across} voices.}
931 Notation Reference: @ruser{Multiple voices}.
934 @node Explicitly instantiating voices
935 @subsection Explicitly instantiating voices
941 @funindex \voiceThree
948 @cindex voice contexts, creating
950 Voice contexts can also be created manually
951 inside a @code{<< >>} block to create polyphonic music, using
952 @code{\voiceOne} @dots{} @code{\voiceFour} to indicate the required
953 directions of stems, slurs, etc. In longer scores this method
954 is clearer, as it permits the voices to be separated and to be
955 given more descriptive names.
957 Specifically, the construct @code{<< \\ >>} which we used in
958 the previous section:
963 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
973 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
974 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
978 Both of the above would produce
980 @c The following example should not display the code
981 @lilypond[ragged-right,quote]
983 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
984 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
988 @cindex voices, reverting to single
989 @cindex reverting to a single voice
991 The @code{\voiceXXX} commands set the direction of stems, slurs,
992 ties, articulations, text annotations, augmentation dots of dotted
993 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
994 make these objects point upwards, while @code{\voiceTwo} and
995 @code{\voiceFour} make them point downwards. These commands also
996 generate a horizontal shift for each voice when this is required
997 to avoid clashes of note heads. The command @code{\oneVoice}
998 reverts the settings back to the normal values for a single voice.
1000 Let us see in some simple examples exactly what effect
1001 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
1002 markup, ties, slurs, and dynamics:
1004 @lilypond[quote,ragged-right,verbatim]
1006 % Default behavior or behavior after \oneVoice
1007 c4 d8~ 8 e4( f | g4 a) b-> c |
1011 @lilypond[quote,ragged-right,verbatim]
1014 c4 d8~ 8 e4( f | g4 a) b-> c |
1016 c,4 d8~ 8 e4( f | g4 a) b-> c |
1020 @lilypond[quote,ragged-right,verbatim]
1023 c4 d8~ 8 e4( f | g4 a) b-> c |
1025 c,4 d8~ 8 e4( f | g4 a) b-> c |
1029 Now let's look at three different ways to notate the same passage of
1030 polyphonic music, each of which is advantageous in different
1031 circumstances, using the example from the previous section.
1033 An expression that appears directly inside a @code{<< >>} belongs to the
1034 main voice (but, note, @strong{not} in a @code{<< \\ >>} construct).
1035 This is useful when extra voices appear while the main voice is playing.
1036 Here is a more correct rendition of our example. The red diamond-shaped
1037 notes demonstrate that the main melody is now in a single voice context,
1038 permitting a phrasing slur to be drawn over them.
1040 @lilypond[quote,ragged-right,verbatim]
1041 \new Staff \relative c' {
1043 % This section is homophonic
1045 % Start simultaneous section of three voices
1047 % Continue the main voice in parallel
1048 { g4 f e | d2 e) | }
1049 % Initiate second voice
1051 % Set stems, etc., down
1053 r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
1055 % Initiate third voice
1057 % Set stems, etc, up
1065 @cindex nesting music expressions
1066 @cindex nesting simultaneous constructs
1067 @cindex nesting voices
1068 @cindex voices, temporary
1069 @cindex voices, nesting
1071 More deeply nested polyphony constructs are possible, and if a
1072 voice appears only briefly this might be a more natural way to
1075 @lilypond[quote,ragged-right,verbatim]
1076 \new Staff \relative c' {
1079 { g4 f e | d2 e) | }
1084 { c8 b16 a b8 g~ 2 | }
1095 @cindex spacing notes
1097 This method of nesting new voices briefly is useful
1098 when only small sections of the music
1099 are polyphonic, but when the whole staff is largely polyphonic
1100 it can be clearer to use multiple voices throughout, using
1101 spacing notes to step over sections where the voice is silent,
1104 @lilypond[quote,ragged-right,verbatim]
1105 \new Staff \relative c' <<
1106 % Initiate first voice
1109 c16^( d e f g4 f e | d2 e) |
1111 % Initiate second voice
1113 % Set stems, etc, down
1115 s4 r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
1117 % Initiate third voice
1119 % Set stems, etc, up
1126 @subsubheading Note columns
1129 @cindex note collisions
1130 @cindex collisions, notes
1131 @cindex shift commands
1138 @funindex \shiftOnnn
1141 Closely spaced notes in a chord, or notes occurring at the same
1142 time in different voices, are arranged in two, occasionally more,
1143 columns to prevent the note heads overlapping. These are called
1144 note columns. There are separate columns for each voice, and
1145 the currently specified voice-dependent shift is applied to the
1146 note column if there would otherwise be a collision. This can
1147 be seen in the example above. In bar 2 the C in voice two is
1148 shifted to the right relative to the D in voice one, and in the
1149 final chord the C in voice three is also shifted to the right
1150 relative to the other notes.
1152 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1153 @code{\shiftOff} commands specify the degree to which notes and
1154 chords of the voice should be shifted if a collision
1155 would otherwise occur. By default, the outer voices (normally
1156 voices one and two) have @code{\shiftOff} specified, while the
1157 inner voices (three and four) have @code{\shiftOn} specified.
1158 When a shift is applied, voices one and three are shifted to
1159 the right and voices two and four to the left.
1161 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1162 levels which may be specified temporarily to resolve collisions
1163 in complex situations -- see @ref{Real music example}.
1165 A note column can contain just one note (or chord) from a voice
1166 with stems up and one note (or chord) from a voice with stems
1167 down. If notes from two voices which have their stems in the
1168 same direction are placed at the same position and both voices
1169 have no shift or the same shift specified, the error message
1170 @qq{Too many clashing note columns} will be produced.
1175 @ref{Moving objects}.
1178 @ruser{Multiple voices}.
1181 @node Voices and vocals
1182 @subsection Voices and vocals
1184 Vocal music presents a special difficulty: we need to combine two
1185 expressions -- notes and lyrics.
1187 @funindex \new Lyrics
1191 @cindex Lyrics context, creating
1192 @cindex lyrics, linking to voice
1194 You have already seen the @code{\addlyrics@{@}} command, which
1195 handles simple scores well. However, this technique is
1196 quite limited. For more complex music, you must introduce the
1197 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1199 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1200 name assigned to the Voice.
1202 @lilypond[quote,verbatim]
1204 \new Voice = "one" {
1208 c4 b8. a16 | g4. f8 | e4 d | c2 |
1211 \new Lyrics \lyricsto "one" {
1212 No more let | sins and | sor -- rows | grow. |
1217 Note that the lyrics must be linked to a @code{Voice} context,
1218 @emph{not} a @code{Staff} context. This is a case where it is
1219 necessary to create @code{Staff} and @code{Voice} contexts
1222 @cindex lyrics and beaming
1223 @cindex beaming and lyrics
1224 @funindex \autoBeamOff
1225 @funindex autoBeamOff
1227 The automatic beaming which LilyPond uses by default works well
1228 for instrumental music, but not so well for music with lyrics,
1229 where beaming is either not required at all or is used to indicate
1230 melismata in the lyrics. In the example above we use the command
1231 @code{\autoBeamOff} to turn off the automatic beaming.
1233 @funindex \new ChoirStaff
1234 @funindex ChoirStaff
1235 @funindex \lyricmode
1237 @cindex vocal score structure
1240 Let us reuse the earlier example from Judas Maccabæus to
1241 illustrate this more flexible technique. We first recast
1242 it to use variables so the music and lyrics can be separated
1243 from the staff structure. We also introduce a ChoirStaff
1244 bracket. The lyrics themselves must be introduced with
1245 @code{\lyricmode} to ensure they are interpreted as lyrics
1248 @lilypond[quote,verbatim]
1249 global = { \key f \major \time 6/8 \partial 8 }
1251 SopOneMusic = \relative c'' {
1252 c8 | c8([ bes)] a a([ g)] f | f'4. b, | c4.~ 4
1254 SopOneLyrics = \lyricmode {
1255 Let | flee -- cy flocks the | hills a -- dorn, __
1257 SopTwoMusic = \relative c' {
1258 r8 | r4. r4 c8 | a'8([ g)] f f([ e)] d | e8([ d)] c bes'
1260 SopTwoLyrics = \lyricmode {
1261 Let | flee -- cy flocks the | hills a -- dorn,
1267 \new Voice = "SopOne" {
1271 \new Lyrics \lyricsto "SopOne" {
1276 \new Voice = "SopTwo" {
1280 \new Lyrics \lyricsto "SopTwo" {
1288 This is the basic structure of all vocal scores. More staves may be
1289 added as required, more voices may be added to the staves, more verses
1290 may be added to the lyrics, and the variables containing the music can
1291 easily be placed in separate files should they become too long.
1293 @cindex hymn structure
1294 @cindex SATB structure
1295 @cindex vocal scores with multiple verses
1296 @cindex multiple vocal verses
1297 @cindex verses, multiple vocal
1299 Here is an example of the first line of a hymn with four
1300 verses, set for SATB. In this case the words for all four
1301 parts are the same. Note how we use variables to separate the
1302 music notation and words from the staff structure. See too
1303 how a variable, which we have chosen to call @q{keyTime}, is used
1304 to hold several commands for use within the two staves. In other
1305 examples this is often called @q{global}.
1307 @lilypond[quote,verbatim]
1308 keyTime = { \key c \major \time 4/4 \partial 4 }
1310 SopMusic = \relative c' { c4 | e4. e8 g4 g | a4 a g }
1311 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f4 f e }
1312 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1313 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1316 \lyricmode { E -- | ter -- nal fa -- ther, | strong to save, }
1318 \lyricmode { O | Christ, whose voice the | wa -- ters heard, }
1320 \lyricmode { O | Ho -- ly Spi -- rit, | who didst brood }
1322 \lyricmode { O | Tri -- ni -- ty of | love and pow'r }
1328 \new Voice = "Sop" { \voiceOne \keyTime \SopMusic }
1329 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1330 \new Lyrics \lyricsto "Sop" { \VerseOne }
1331 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1332 \new Lyrics \lyricsto "Sop" { \VerseThree }
1333 \new Lyrics \lyricsto "Sop" { \VerseFour }
1337 \new Voice = "Tenor" { \voiceOne \keyTime \TenorMusic }
1338 \new Voice = "Bass" { \voiceTwo \BassMusic }
1346 Notation Reference: @ruser{Vocal music}.
1349 @node Contexts and engravers
1350 @section Contexts and engravers
1352 Contexts and engravers have been mentioned informally
1353 in earlier sections; we now must look at
1354 these concepts in more detail, as they are important
1355 in the fine-tuning of LilyPond output.
1359 * Contexts explained::
1360 * Creating contexts::
1361 * Engravers explained::
1362 * Modifying context properties::
1363 * Adding and removing engravers::
1366 @node Contexts explained
1367 @subsection Contexts explained
1369 @cindex contexts explained
1371 When music is printed, many notational elements which do not
1372 appear explicitly in the input file must be added to the
1373 output. For example, compare the input and output of the
1376 @lilypond[quote,verbatim,relative=2]
1377 cis4 cis2. | a4 a2. |
1380 The input is rather sparse, but in the output, bar lines,
1381 accidentals, clef, and time signature have been added. When
1382 LilyPond @emph{interprets} the input the musical information
1383 is parsed from left to right, similar to the way a performer
1384 reads the score. While reading the input, the program remembers
1385 where measure boundaries are, and which pitches require explicit
1386 accidentals. This information must be held on several levels.
1387 For example, an accidental affects only a single staff, while
1388 a bar line must be synchronized across the entire score.
1390 Within LilyPond, these rules and bits of information are grouped in
1391 @emph{Contexts}. We have already introduced the @code{Voice} context.
1392 Others are the @code{Staff} and @code{Score} contexts. Contexts are
1393 hierarchical to reflect the hierarchical nature of a musical score.
1394 For example: a @code{Staff} context can contain many @code{Voice}
1395 contexts, and a @code{Score} context can contain many @code{Staff}
1399 @sourceimage{context-example,5cm,,}
1402 Each context has the responsibility for enforcing some notation rules,
1403 creating some notation objects and maintaining the associated
1404 properties. For example, the @code{Voice} context may introduce an
1405 accidental and then the @code{Staff} context maintains the rule to
1406 show or suppress the accidental for the remainder of the measure.
1408 As another example, the synchronization of bar lines is, by default,
1409 handled in the @code{Score} context.
1410 However, in some music we may not want the bar lines to be
1411 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1412 In such cases, we must modify the default settings of the
1413 @code{Score} and @code{Staff} contexts.
1415 For very simple scores, contexts are created implicitly, and you need
1416 not be aware of them. For larger pieces, such as anything with more
1417 than one staff, they must be
1418 created explicitly to make sure that you get as many staves as you
1419 need, and that they are in the correct order. For typesetting pieces
1420 with specialized notation, it is usual to modify existing, or
1421 even to define totally new, contexts.
1423 In addition to the @code{Score,} @code{Staff} and
1424 @code{Voice} contexts there are contexts which fit between
1425 the score and staff levels to control staff groups, such as the
1426 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1427 are also alternative staff and voice contexts, and contexts for
1428 lyrics, percussion, fret boards, figured bass, etc.
1430 The names of all context types are formed from one or more
1431 words, each word being capitalized and joined immediately to the
1432 preceding word with no hyphen or underscore, e.g.,
1433 @code{GregorianTranscriptionStaff}.
1437 Notation Reference: @ruser{Contexts explained}.
1440 @node Creating contexts
1441 @subsection Creating contexts
1445 @cindex new contexts
1446 @cindex creating contexts
1447 @cindex contexts, creating
1449 In an input file a score block, introduced with a @code{\score}
1450 command, contains a single music expression and an associated
1451 output definition (either a @code{\layout} or a @code{\midi} block).
1452 The @code{Score} context is usually left to be created automatically
1453 when the interpretation of that music expression starts.
1455 For scores with only one voice and one staff, the @code{Voice} and
1456 @code{Staff} contexts may also be left to be created automatically,
1457 but for more complex scores it is necessary to create them by hand.
1458 The simplest command that does this is @code{\new}. It is prepended
1459 to a music expression, for example
1462 \new @var{type} @var{music-expression}
1466 where @var{type} is a context name (like @code{Staff} or
1467 @code{Voice}). This command creates a new context, and starts
1468 interpreting the @var{music-expression} within that context.
1470 @warning{@bs{}@code{new Score} should not be used as the essential
1471 top-level @code{Score} context is created automatically when the music
1472 expression within the @bs{}@code{score} block is interpreted. Score-wide
1473 default values of context properties can be changed within the
1474 @bs{}@code{layout} block. See @ref{Modifying context properties}}
1476 You have seen many practical examples which created new
1477 @code{Staff} and @code{Voice} contexts in earlier sections, but
1478 to remind you how these commands are used in practice, here's an
1479 annotated real-music example:
1481 @lilypond[quote,verbatim,ragged-right]
1482 \score { % start of single compound music expression
1483 << % start of simultaneous staves section
1485 \new Staff { % create RH staff
1488 \new Voice { % create voice for RH notes
1489 \relative c'' { % start of RH notes
1495 \new Staff << % create LH staff; needs two simultaneous voices
1498 \new Voice { % create LH voice one
1500 \relative g { % start of LH voice one notes
1501 g8 <bes d> ees, <g c> |
1502 g8 <bes d> ees, <g c> |
1503 } % end of LH voice one notes
1504 } % end of LH voice one
1505 \new Voice { % create LH voice two
1507 \relative g { % start of LH voice two notes
1510 } % end of LH voice two notes
1511 } % end of LH voice two
1512 >> % end of LH staff
1513 >> % end of simultaneous staves section
1514 } % end of single compound music expression
1517 (Note how all the statements which open a block with either a
1518 curly bracket, @code{@{}, or double angle brackets, @code{<<},
1519 are indented by two further spaces, and the corresponding
1520 closing bracket is indented by exactly the same amount. While
1521 this is not required, following this practice will greatly
1522 reduce the number of @q{unmatched bracket} errors, and is
1523 strongly recommended. It enables the structure of the music to
1524 be seen at a glance, and any unmatched brackets will be obvious.
1525 Note too how the LH staff is created using double angle brackets
1526 because it requires two voices for its music, whereas the RH staff
1527 is created with a single music expression surrounded by curly
1528 brackets because it requires only one voice.)
1530 @cindex contexts, naming
1531 @cindex naming contexts
1533 The @code{\new} command may also give an identifying name to the
1534 context to distinguish it from other contexts of the same type,
1537 \new @var{type} = @var{id} @var{music-expression}
1540 Note the distinction between the name of the context type,
1541 @code{Staff}, @code{Voice}, etc, and the identifying name of a
1542 particular instance of that type, which can be any sequence of letters
1543 invented by the user. Digits and spaces can also be used in the
1544 identifying name, but then it has to be placed in quotes,
1545 i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
1546 The identifying name is used to
1547 refer back to that particular instance of a context. We saw this in
1548 use in the section on lyrics, see @ref{Voices and vocals}.
1552 Notation Reference: @ruser{Creating and referencing contexts}.
1555 @node Engravers explained
1556 @subsection Engravers explained
1560 Every mark on the printed output of a score produced by LilyPond
1561 is produced by an @code{Engraver}. Thus there is an engraver
1562 to print staves, one to print note heads, one for stems, one for
1563 beams, etc, etc. In total there are over 120 such engravers!
1564 Fortunately, for most scores it is not necessary to know about
1565 more than a few, and for simple scores you do not need to know
1568 Engravers live and operate in Contexts. Engravers such as the
1569 @code{Metronome_mark_engraver}, whose action and output apply to the
1570 score as a whole, operate in the highest level context -- the
1571 @code{Score} context.
1573 The @code{Clef_engraver} and @code{Key_engraver} are to be
1574 found in every @code{Staff} Context, as different staves may require
1575 different clefs and keys.
1577 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1578 in every @code{Voice} context, the lowest level context of all.
1580 Each engraver processes the particular objects associated
1581 with its function, and maintains the properties that relate
1582 to that function. These properties, like the properties
1583 associated with contexts, may be modified to change the
1584 operation of the engraver or the appearance of those elements
1585 in the printed score.
1587 Engravers all have compound names formed from words which
1588 describe their function. Just the first word is capitalized,
1589 and the remainder are joined to it with underscores. Thus
1590 the @code{Staff_symbol_engraver} is responsible for creating the
1591 lines of the staff, the @code{Clef_engraver} determines and sets
1592 the pitch reference point on the staff by drawing a clef symbol.
1594 Here are some of the most common engravers together with their
1595 function. You will see it is usually easy to guess the function
1596 from the name, or vice versa.
1598 @multitable @columnfractions .3 .7
1601 @item Accidental_engraver
1602 @tab Makes accidentals, cautionary and suggested accidentals
1607 @item Completion_heads_engraver
1608 @tab Splits notes which cross bar lines
1609 @item Dynamic_engraver
1610 @tab Creates hairpins and dynamic texts
1611 @item Forbid_line_break_engraver
1612 @tab Prevents line breaks if a musical element is still active
1614 @tab Creates the key signature
1615 @item Metronome_mark_engraver
1616 @tab Engraves metronome marking
1617 @item Note_heads_engraver
1618 @tab Engraves note heads
1621 @item Staff_symbol_engraver
1622 @tab Engraves the five (by default) lines of the staff
1624 @tab Creates stems and single-stem tremolos
1625 @item Time_signature_engraver
1626 @tab Creates time signatures
1631 We shall see later how the output of LilyPond can be changed
1632 by modifying the action of Engravers.
1636 Internals reference: @rinternals{Engravers and Performers}.
1639 @node Modifying context properties
1640 @subsection Modifying context properties
1642 @cindex context properties
1643 @cindex context properties, modifying
1644 @cindex modifying context properties
1650 Contexts are responsible for holding the values of a number of
1651 context @emph{properties}. Many of them can be changed to
1652 influence the interpretation of the input and so change the
1653 appearance of the output. They are changed by the
1654 @code{\set} command. This takes the form
1657 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1660 Where the @emph{ContextName} is usually @code{Score},
1661 @code{Staff} or @code{Voice}. It may be omitted,
1662 in which case the current context (typically @code{Voice}) is assumed.
1664 The names of context properties consist of words joined
1665 together with no hyphens or underscores, all except the
1666 first having a capital letter. Here are a few examples
1667 of some commonly used ones. There are many more.
1669 @c attempt to force this onto a new page
1671 @multitable @columnfractions .25 .15 .45 .15
1672 @headitem propertyName
1678 @tab If true, set extra natural signs before accidentals
1679 @tab @code{#t}, @code{#f}
1680 @item currentBarNumber
1682 @tab Set the current bar number
1686 @tab If true, print slurs both above and below notes
1687 @tab @code{#t}, @code{#f}
1688 @item instrumentName
1690 @tab Set the name to be placed at the start of the staff
1691 @tab @code{"Cello I"}
1694 @tab Increase or decrease the font size
1698 @tab Set the text to print before the start of a verse
1703 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1704 an Integer is a positive whole number, a Real is a positive
1705 or negative decimal number, and text is enclosed in double
1706 apostrophes. Note the occurrence of hash signs,
1707 (@code{#}), in two different places -- as part of the Boolean
1708 value before the @code{t} or @code{f}, and before @emph{value}
1709 in the @code{\set} statement. So when a Boolean is being
1710 entered you need to code two hash signs, e.g., @code{##t}.
1712 @cindex properties operating in contexts
1713 @cindex setting properties within contexts
1715 Before we can set any of these properties we need to know
1716 in which context they operate. Sometimes this is obvious,
1717 but occasionally it can be tricky. If the wrong context
1718 is specified, no error message is produced, but the expected
1719 action will not take place. For example, the
1720 @code{instrumentName} clearly lives in the @code{Staff} context, since
1721 it is the staff that is to be named.
1722 In this example the first staff is labeled, but not the second,
1723 because we omitted the context name.
1725 @lilypond[quote,verbatim,ragged-right]
1727 \new Staff \relative c'' {
1728 \set Staff.instrumentName = #"Soprano"
1731 \new Staff \relative c' {
1732 \set instrumentName = #"Alto" % Wrong!
1738 Remember the default context name is @code{Voice}, so the second
1739 @code{\set} command set the property @code{instrumentName} in the
1740 @code{Voice} context to @qq{Alto}, but as LilyPond does not look
1741 for any such property in the @code{Voice} context, no
1742 further action took place. This is not an error, and no error
1743 message is logged in the log file.
1745 Similarly, if the property name is mis-spelt no error message is
1746 produced, and clearly the expected action cannot be performed. In
1747 fact, you can set any (fictitious) @q{property} using any name you
1748 like in any context that exists by using the @code{\set} command. But
1749 if the name is not known to LilyPond it will not cause any action to
1750 be taken. Some text editors with special support for LilyPond input
1751 files document property names with bullets when you hover them with
1752 the mouse, like JEdit with LilyPondTool, or highlight unknown property
1753 names differently, like ConTEXT. If you do not use an editor with
1754 such features, it is recommended to check the property name in the
1755 Internals Reference: see @rinternals{Tunable context properties}, or
1756 @rinternals{Contexts}.
1758 The @code{instrumentName} property will take effect only
1759 if it is set in the @code{Staff} context, but
1760 some properties can be set in more than one context.
1761 For example, the property @code{extraNatural} is by
1762 default set to ##t (true) for all staves.
1763 If it is set to ##f (false) in one particular @code{Staff}
1764 context it applies just to the accidentals on that staff.
1765 If it is set to false in the @code{Score} context
1766 it applies to all staves.
1768 So this turns off extra naturals in one staff:
1770 @lilypond[quote,verbatim,ragged-right]
1772 \new Staff \relative c'' {
1775 \new Staff \relative c'' {
1776 \set Staff.extraNatural = ##f
1783 and this turns them off in all staves:
1785 @lilypond[quote,verbatim,ragged-right]
1787 \new Staff \relative c'' {
1790 \new Staff \relative c'' {
1791 \set Score.extraNatural = ##f
1797 As another example, if @code{clefTransposition} is set in
1798 the @code{Score} context this immediately changes the value
1799 of the transposition in all current staves and sets a new default
1800 value which will be applied to all staves.
1802 The opposite command, @code{\unset}, effectively removes the
1803 property from the context, which causes most properties to
1804 revert to their default value. Usually @code{\unset} is not
1805 required as a new @code{\set} command will achieve what is
1808 The @code{\set} and @code{\unset} commands can appear anywhere
1809 in the input file and will take effect from the time they are
1810 encountered until the end of the score or until the property is
1811 @code{\set} or @code{\unset} again. Let's try changing the
1812 font size, which affects the size of the note heads (among
1813 other things) several times. The change is from the default
1814 value, not the most recently set value.
1816 @lilypond[quote,verbatim,ragged-right,relative=1]
1818 % make note heads smaller
1821 % make note heads larger
1822 \set fontSize = #2.5
1824 % return to default size
1829 We have now seen how to set the values of several different types of
1830 property. Note that integers and numbers are always preceded by a
1831 hash sign, @code{#}, while a true or false value is specified by
1832 @code{##t} and @code{##f}, with two hash signs. A text property
1833 should be enclosed in double quotation signs, as above, although we
1834 shall see later that text can actually be specified in a much more
1835 general way by using the very powerful @code{\markup} command.
1837 @subsubheading Setting context properties with @code{\with}
1841 @cindex context properties, setting with \with
1843 The default value of context properties may be set at the time the
1844 context is created. Sometimes this is a clearer way of setting a
1845 property value if it is to remain fixed for the duration of
1846 the context. When a context is created with a @code{\new}
1847 command it may be followed immediately by a @code{\with @{ @dots{} @}}
1848 block in which the default property values are set. For example,
1849 if we wish to suppress the printing of extra naturals for the
1850 duration of a staff we would write:
1853 \new Staff \with @{ extraNatural = ##f @}
1859 @lilypond[quote,verbatim,ragged-right]
1863 gisis4 gis aeses aes
1866 \new Staff \with { extraNatural = ##f } {
1868 gisis4 gis aeses aes
1874 Properties set in this way may still be changed dynamically using
1875 @code{\set} and returned to the default value set in the
1876 @code{\with} block with @code{\unset}.
1878 @cindex fontSize, default and setting
1880 So if the @code{fontSize} property is set in a @code{\with} clause
1881 it sets the default value of the font size. If it is later changed
1882 with @code{\set}, this new default value may be restored with the
1883 @code{\unset fontSize} command.
1885 @subsubheading Setting context properties with @code{\context}
1887 @cindex context properties, setting with \context
1891 The values of context properties may be set in @emph{all} contexts
1892 of a particular type, such as all @code{Staff} contexts, with a single
1893 command. The context type is identified by using its
1894 type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
1895 The statement which sets the property value is the same as that in a
1896 @code{\with} block, introduced above. It is placed in a
1897 @code{\context} block within a @code{\layout} block. Each
1898 @code{\context} block will affect all contexts of the type specified
1899 throughout the @code{\score} or @code{\book} block in which the
1900 @code{\layout} block appears. Here is an example to show the format:
1902 @lilypond[verbatim,quote]
1918 If the property override is to be applied to all staves
1921 @lilypond[quote,verbatim]
1926 gisis4 gis aeses aes
1931 gisis4 gis aeses aes
1937 \Score extraNatural = ##f
1944 Context properties set in this way may be overridden for particular
1945 instances of contexts by statements in a @code{\with} block, and by
1946 @code{\set} commands embedded in music statements.
1951 @ruser{Changing context default settings}.
1952 @ruser{The set command}.
1954 Internals Reference:
1955 @rinternals{Contexts},
1956 @rinternals{Tunable context properties}.
1959 @node Adding and removing engravers
1960 @subsection Adding and removing engravers
1962 @cindex engravers, adding
1963 @cindex adding engravers
1964 @cindex engravers, removing
1965 @cindex removing engravers
1972 We have seen that contexts each contain several engravers, each
1973 of which is responsible for producing a particular part of the
1974 output, like bar lines, staves, note heads, stems, etc. If an
1975 engraver is removed from a context, it can no longer produce its
1976 output. This is a crude way of modifying the output, but it
1977 can sometimes be useful.
1979 @subsubheading Changing a single context
1981 To remove an engraver from a single context we use the
1982 @code{\with} command placed immediately after the context creation
1983 command, as in the previous section.
1985 As an illustration, let's repeat an example from the previous section
1986 with the staff lines removed. Remember that the staff lines are
1987 produced by the @code{Staff_symbol_engraver}.
1989 @lilypond[quote,verbatim,ragged-right]
1991 \remove "Staff_symbol_engraver"
1995 \set fontSize = #-4 % make note heads smaller
1997 \set fontSize = #2.5 % make note heads larger
1999 \unset fontSize % return to default size
2004 @cindex ambitus engraver
2006 Engravers can also be added to individual contexts.
2007 The command to do this is
2009 @code{\consists @var{Engraver_name}},
2012 placed inside a @code{\with} block. Some vocal scores have an ambitus
2013 placed at the beginning of a staff to indicate the range of notes in
2014 that staff -- see @rglos{ambitus}. The ambitus is produced by the
2015 @code{Ambitus_engraver}, which is not normally included in any
2016 context. If we add it to the @code{Voice} context, it calculates the
2017 range from that voice only:
2019 @lilypond[quote,verbatim,ragged-right]
2022 \consists "Ambitus_engraver"
2039 but if we add the ambitus engraver to the
2040 @code{Staff} context, it calculates the range from all
2041 the notes in all the voices on that staff:
2043 @lilypond[quote,verbatim,ragged-right]
2045 \consists "Ambitus_engraver"
2063 @subsubheading Changing all contexts of the same type
2068 The examples above show how to remove or add engravers to
2069 individual contexts. It is also possible to remove or add
2070 engravers to every context of a specific type by placing the
2071 commands in the appropriate context in a @code{\layout}
2072 block. For example, if we wanted to show an ambitus for every
2073 staff in a four-staff score, we could write
2075 @lilypond[quote,verbatim,ragged-right]
2104 \consists "Ambitus_engraver"
2111 The values of context properties may also be set
2112 for all contexts of a particular type by including the
2113 @code{\set} command in a @code{\context} block in the
2117 Notation Reference: @ruser{Modifying context plug-ins},
2118 @ruser{Changing context default settings}.
2121 The @code{Stem_engraver} and @code{Beam_engraver} attach their
2122 objects to note heads. If the @code{Note_heads_engraver} is removed
2123 no note heads are produced and therefore no stems or beams are created
2127 @node Extending the templates
2128 @section Extending the templates
2130 You've read the tutorial, you know how to write music, you
2131 understand the fundamental concepts. But how can you
2132 get the staves that you want? Well, you can find lots of
2133 templates (see @ref{Templates}) which may give you a start.
2134 But what if you want something that isn't covered there? Read on.
2137 * Soprano and cello::
2138 * Four-part SATB vocal score::
2139 * Building a score from scratch::
2140 * Saving typing with variables and functions::
2141 * Scores and parts::
2144 @node Soprano and cello
2145 @subsection Soprano and cello
2147 @cindex template, modifying
2148 @cindex modifying templates
2150 Start off with the template that seems closest to what you want to
2151 end up with. Let's say that you want to write something for
2152 soprano and cello. In this case, we would start with the
2153 @q{Notes and lyrics} template (for the soprano part).
2156 \version @w{"@version{}"}
2158 melody = \relative c' @{
2165 text = \lyricmode @{
2171 \new Voice = "one" @{
2175 \new Lyrics \lyricsto "one" \text
2182 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2185 \version @w{"@version{}"}
2187 melody = \relative c' @{
2201 We don't need two @code{\version} commands. We'll need the
2202 @code{melody} section. We don't want two @code{\score} sections
2203 -- if we had two @code{\score}s, we'd get the two parts separately.
2204 We want them together, as a duet. Within the @code{\score}
2205 section, we don't need two @code{\layout} or @code{\midi}.
2207 If we simply cut and paste the @code{melody} section, we would
2208 end up with two @code{melody} definitions. This would not generate
2209 an error, but the second one would be used for both melodies.
2210 So let's rename them to make them distinct. We'll call the
2211 section for the soprano @code{sopranoMusic} and the section for
2212 the cello @code{celloMusic}. While we're doing this, let's rename
2213 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2214 instances of all these names -- both the initial definition (the
2215 @code{melody = \relative c' @{ } part) and the name's use (in the
2216 @code{\score} section).
2218 While we're doing this, let's change the cello part's staff --
2219 celli normally use bass clef. We'll also give the cello some
2223 \version @w{"@version{}"}
2225 sopranoMusic = \relative c' @{
2232 sopranoLyrics = \lyricmode @{
2236 celloMusic = \relative c @{
2245 \new Voice = "one" @{
2249 \new Lyrics \lyricsto "one" \sopranoLyrics
2256 This is looking promising, but the cello part won't appear in the
2257 score -- we haven't used it in the @code{\score} section. If we
2258 want the cello part to appear under the soprano part, we need to add
2261 \new Staff \celloMusic
2265 underneath the soprano stuff. We also need to add @code{<<} and
2266 @code{>>} around the music -- that tells LilyPond that there's
2267 more than one thing (in this case, two @code{Staves}) happening
2268 at once. The @code{\score} looks like this now:
2270 @c Indentation in this example is deliberately poor
2275 \new Voice = "one" @{
2279 \new Lyrics \lyricsto "one" \sopranoLyrics
2281 \new Staff \celloMusic
2289 This looks a bit messy; the indentation is messed up now. That is
2290 easily fixed. Here's the complete soprano and cello template.
2292 @lilypond[quote,verbatim,ragged-right,addversion]
2293 sopranoMusic = \relative c' {
2300 sopranoLyrics = \lyricmode {
2304 celloMusic = \relative c {
2314 \new Voice = "one" {
2318 \new Lyrics \lyricsto "one" \sopranoLyrics
2320 \new Staff \celloMusic
2329 The starting templates can be found in the @q{Templates} appendix,
2330 see @ref{Single staff templates}.
2333 @node Four-part SATB vocal score
2334 @subsection Four-part SATB vocal score
2336 @cindex template, SATB
2337 @cindex SATB template
2339 Most vocal scores of music written for four-part mixed choir
2340 with orchestral accompaniment such as Mendelssohn's Elijah or
2341 Handel's Messiah have the choral music and words on four
2342 staves, one for each of SATB, with a piano reduction of the
2343 orchestral accompaniment underneath. Here's an example
2344 from Handel's Messiah:
2346 @c The following should appear as music without code
2347 @lilypond[quote,ragged-right]
2348 global = { \key d \major \time 4/4 }
2350 sopranoMusic = \relative c'' {
2352 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2354 sopranoWords = \lyricmode {
2355 Wor -- thy | is the lamb | that was slain |
2358 altoMusic = \relative a' {
2360 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
2362 altoWords = \sopranoWords
2364 tenorMusic = \relative c' {
2366 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2368 tenorWords = \sopranoWords
2370 bassMusic = \relative c' {
2372 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2374 bassWords = \sopranoWords
2376 upper = \relative a' {
2379 r4 <a d fis>2 <a e' a>4 |
2380 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2381 <g cis g'>4 <a d fis> <a cis e>2 |
2384 lower = \relative c, {
2387 <d d'>4 <d d'>2 <cis cis'>4 |
2388 <b b'>4. <b' b'>8 <fis fis'>2 |
2389 <e e'>4 <d d'> <a' a'>2 |
2393 << % combine ChoirStaff and PianoStaff in parallel
2395 \new Staff = "sopranos" <<
2396 \set Staff.instrumentName = #"Soprano"
2397 \new Voice = "sopranos" {
2402 \new Lyrics \lyricsto "sopranos" {
2405 \new Staff = "altos" <<
2406 \set Staff.instrumentName = #"Alto"
2407 \new Voice = "altos" {
2412 \new Lyrics \lyricsto "altos" { \altoWords }
2413 \new Staff = "tenors" <<
2414 \set Staff.instrumentName = #"Tenor"
2415 \new Voice = "tenors" {
2420 \new Lyrics \lyricsto "tenors" { \tenorWords }
2421 \new Staff = "basses" <<
2422 \set Staff.instrumentName = #"Bass"
2423 \new Voice = "basses" {
2428 \new Lyrics \lyricsto "basses" {
2433 \set PianoStaff.instrumentName = #"Piano"
2434 \new Staff = "upper" \upper
2435 \new Staff = "lower" \lower
2441 @warning{This layout can be achieved very easily using the built-in
2442 template: @code{satb.ly}, see @ref{Built-in templates}. But for ease
2443 of use this template deliberately hides the necessary context
2444 structure, instead providing it automatically. So for purposes of
2445 learning let us see how to build this up from scratch. You may need
2446 to do this if the built-in template does not meet your needs
2449 The nearest copy-and-edit template to this layout is
2450 @ref{SATB vocal score and automatic piano reduction} -- but we need
2451 to change the layout and add a piano
2452 accompaniment which is not derived automatically from the vocal parts.
2453 The variables holding the music and words for the vocal parts are
2454 fine, but we shall need to add variables for the piano reduction.
2456 The order in which the contexts appear in the ChoirStaff of the
2457 template do not correspond with the order in the vocal score shown
2458 above. We need to rearrange them so there are four staves with the
2459 words written directly underneath the notes for each part. All the
2460 voices should be @code{\voiceOne}, which is the default, so the
2461 @code{\voiceXXX} commands should be removed. We also need to specify
2462 the tenor clef for the tenors. The way in which lyrics are specified
2463 in the template has not yet been encountered so we need to use the
2464 method with which we are familiar. We should also add the names of
2467 Doing this gives for our ChoirStaff:
2471 \new Staff = "sopranos" <<
2472 \set Staff.instrumentName = #"Soprano"
2473 \new Voice = "sopranos" @{
2478 \new Lyrics \lyricsto "sopranos" @{
2481 \new Staff = "altos" <<
2482 \set Staff.instrumentName = #"Alto"
2483 \new Voice = "altos" @{
2488 \new Lyrics \lyricsto "altos" @{
2491 \new Staff = "tenors" <<
2492 \set Staff.instrumentName = #"Tenor"
2493 \new Voice = "tenors" @{
2498 \new Lyrics \lyricsto "tenors" @{
2501 \new Staff = "basses" <<
2502 \set Staff.instrumentName = #"Bass"
2503 \new Voice = "basses" @{
2508 \new Lyrics \lyricsto "basses" @{
2514 Next we must work out the piano part. This is
2515 easy - we just pull out the piano part from the
2516 @q{Solo piano} template:
2520 \set PianoStaff.instrumentName = #"Piano "
2521 \new Staff = "upper" \upper
2522 \new Staff = "lower" \lower
2526 and add the variable definitions for @code{upper}
2529 The ChoirStaff and PianoStaff must be combined
2530 using angle brackets as we want them to be
2531 stacked one above the other:
2534 << % combine ChoirStaff and PianoStaff one above the other
2536 \new Staff = "sopranos" <<
2537 \new Voice = "sopranos" @{
2542 \new Lyrics \lyricsto "sopranos" @{
2545 \new Staff = "altos" <<
2546 \new Voice = "altos" @{
2551 \new Lyrics \lyricsto "altos" @{
2554 \new Staff = "tenors" <<
2555 \clef "G_8" % tenor clef
2556 \new Voice = "tenors" @{
2561 \new Lyrics \lyricsto "tenors" @{
2564 \new Staff = "basses" <<
2566 \new Voice = "basses" @{
2571 \new Lyrics \lyricsto "basses" @{
2577 \set PianoStaff.instrumentName = #"Piano"
2578 \new Staff = "upper" \upper
2579 \new Staff = "lower" \lower
2584 Combining all these together and adding the music
2585 for the three bars of the example above gives:
2587 @lilypond[quote,verbatim,ragged-right,addversion]
2588 global = { \key d \major \time 4/4 }
2589 sopranoMusic = \relative c'' {
2591 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2593 sopranoWords = \lyricmode {
2594 Wor -- thy | is the lamb | that was slain |
2596 altoMusic = \relative a' {
2598 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2600 altoWords = \sopranoWords
2601 tenorMusic = \relative c' {
2603 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2605 tenorWords = \sopranoWords
2606 bassMusic = \relative c' {
2608 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2610 bassWords = \sopranoWords
2611 upper = \relative a' {
2614 r4 <a d fis>2 <a e' a>4 |
2615 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2616 <g cis g'>4 <a d fis> <a cis e>2 |
2618 lower = \relative c, {
2621 <d d'>4 <d d'>2 <cis cis'>4 |
2622 <b b'>4. <b' b'>8 <fis fis'>2 |
2623 <e e'>4 <d d'> <a' a'>2 |
2627 << % combine ChoirStaff and PianoStaff in parallel
2629 \new Staff = "sopranos" <<
2630 \set Staff.instrumentName = #"Soprano"
2631 \new Voice = "sopranos" {
2636 \new Lyrics \lyricsto "sopranos" {
2639 \new Staff = "altos" <<
2640 \set Staff.instrumentName = #"Alto"
2641 \new Voice = "altos" {
2646 \new Lyrics \lyricsto "altos" {
2649 \new Staff = "tenors" <<
2650 \set Staff.instrumentName = #"Tenor"
2651 \new Voice = "tenors" {
2656 \new Lyrics \lyricsto "tenors" {
2659 \new Staff = "basses" <<
2660 \set Staff.instrumentName = #"Bass"
2661 \new Voice = "basses" {
2666 \new Lyrics \lyricsto "basses" {
2672 \set PianoStaff.instrumentName = #"Piano "
2673 \new Staff = "upper" \upper
2674 \new Staff = "lower" \lower
2681 @node Building a score from scratch
2682 @subsection Building a score from scratch
2684 @cindex template, writing your own
2685 @cindex example of writing a score
2686 @cindex writing a score, example
2687 @cindex score, example of writing
2689 After gaining some facility with writing LilyPond code, you
2690 may find that it is easier to build a score from scratch
2691 rather than modifying one of the templates. You can also
2692 develop your own style this way to suit the sort of music you
2693 like. Let's see how to put together the score for an organ
2694 prelude as an example.
2696 We begin with a header section. Here go the title, name
2697 of composer, etc, then come any variable definitions, and
2698 finally the score block. Let's start with these in outline
2699 and fill in the details later.
2701 We'll use the first two bars of Bach's prelude
2702 based on @emph{Jesu, meine Freude} which is written for two
2703 manuals and pedal organ. You can see these two bars of music
2704 at the bottom of this section. The top manual part has two voices,
2705 the lower and pedal organ one each. So we need four
2706 music definitions and one to define the time signature
2710 \version @w{"@version{}"}
2712 title = "Jesu, meine Freude"
2713 composer = "J S Bach"
2715 keyTime = @{ \key c \minor \time 4/4 @}
2716 ManualOneVoiceOneMusic = @{ s1 @}
2717 ManualOneVoiceTwoMusic = @{ s1 @}
2718 ManualTwoMusic = @{ s1 @}
2719 PedalOrganMusic = @{ s1 @}
2725 For now we've just used a spacer note, @code{s1},
2726 instead of the real music. We'll add that later.
2728 Next let's see what should go in the score block.
2729 We simply mirror the staff structure we want.
2730 Organ music is usually written on three staves,
2731 one for each manual and one for the pedals. The
2732 manual staves should be bracketed together, so we
2733 need to use a PianoStaff for them. The first
2734 manual part needs two voices and the second manual
2739 \new Staff = "ManualOne" <<
2741 \ManualOneVoiceOneMusic
2744 \ManualOneVoiceTwoMusic
2746 >> % end ManualOne Staff context
2747 \new Staff = "ManualTwo" <<
2751 >> % end ManualTwo Staff context
2752 >> % end PianoStaff context
2755 Next we need to add a staff for the pedal organ.
2756 This goes underneath the PianoStaff, but it must
2757 be simultaneous with it, so we need angle brackets
2758 around the two. Missing these out would generate
2759 an error in the log file. It's a common mistake
2760 which you'll make sooner or later! Try copying
2761 the final example at the end of this section,
2762 remove these angle brackets, and compile it to
2763 see what errors it generates.
2766 << % PianoStaff and Pedal Staff must be simultaneous
2768 \new Staff = "ManualOne" <<
2770 \ManualOneVoiceOneMusic
2773 \ManualOneVoiceTwoMusic
2775 >> % end ManualOne Staff context
2776 \new Staff = "ManualTwo" <<
2780 >> % end ManualTwo Staff context
2781 >> % end PianoStaff context
2782 \new Staff = "PedalOrgan" <<
2790 It is not necessary to use the simultaneous construct
2791 @code{<< @dots{} >>} for the manual two staff and the pedal organ staff,
2792 since they contain only one music expression, but it does no harm,
2793 and always using angle brackets after @code{\new Staff} is a good
2794 habit to cultivate in case there are multiple voices. The opposite
2795 is true for Voices: these should habitually be followed by braces
2796 @code{@{ @dots{} @}} in case your music is coded in several variables
2797 which need to run consecutively.
2799 Let's add this structure to the score block, and adjust the indenting.
2800 We also add the appropriate clefs, ensure stems, ties and slurs in
2801 each voice on the upper staff point to the right direction with
2802 @code{\voiceOne} and @code{\voiceTwo}, and enter the key and time
2803 signature to each staff using our predefined variable, @code{\keyTime}.
2807 << % PianoStaff and Pedal Staff must be simultaneous
2809 \new Staff = "ManualOne" <<
2810 \keyTime % set key and time signature
2814 \ManualOneVoiceOneMusic
2818 \ManualOneVoiceTwoMusic
2820 >> % end ManualOne Staff context
2821 \new Staff = "ManualTwo" <<
2827 >> % end ManualTwo Staff context
2828 >> % end PianoStaff context
2829 \new Staff = "PedalOrgan" <<
2835 >> % end PedalOrgan Staff
2837 @} % end Score context
2840 @cindex stretchability of staves
2841 @cindex staves, stretchability
2843 The above layout of the organ staves is almost perfect; however,
2844 there is a slight defect which is not visible by looking at just a
2845 single system: The distance of the pedal staff to the left hand staff
2846 should behave approximately the same as the right hand staff to the
2847 left hand staff. In particular, the stretchability of staves in a
2848 @code{PianoStaff} context is limited (so that the distance between
2849 the staves for the left and right hand can't become too large), and
2850 the pedal staff should behave similarly.
2852 @cindex sub-properties
2853 @cindex properties, sub-properties
2854 @cindex graphical objects
2855 @cindex objects, graphical
2858 Stretchability of staves can be controlled with the
2859 @code{staff-staff-spacing} property of the
2860 @code{VerticalAxisGroup} @q{graphical object} (commonly called
2861 @q{grob}s within the lilypond documentation) -- don't worry about
2862 the details right now; this is fully explained later. For the
2863 curious, have a look at @ruser{Overview of modifying properties}.
2864 In this case, we want to modify the @code{stretchability}
2865 sub-property only. Again, for the curious, you can find the
2866 default values for the staff-staff-spacing property
2867 in file @file{scm/define-grobs.scm} by looking up the definition
2868 of the @code{VerticalAxisGroup} grob. The value for
2869 @code{stretchability} is taken from the definition of the
2870 @code{PianoStaff} context (in file @file{ly/engraver-init.ly})
2871 so that the values are identical.
2875 << % PianoStaff and Pedal Staff must be simultaneous
2877 \new Staff = "ManualOne" <<
2878 \keyTime % set key and time signature
2882 \ManualOneVoiceOneMusic
2886 \ManualOneVoiceTwoMusic
2888 >> % end ManualOne Staff context
2889 \new Staff = "ManualTwo" \with @{
2890 \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
2897 >> % end ManualTwo Staff context
2898 >> % end PianoStaff context
2899 \new Staff = "PedalOrgan" <<
2905 >> % end PedalOrgan Staff
2907 @} % end Score context
2909 That completes the structure. Any three-staff organ music
2910 will have a similar structure, although the number of voices
2911 may vary. All that remains now
2912 is to add the music, and combine all the parts together.
2914 @lilypond[quote,verbatim,ragged-right,addversion]
2916 title = "Jesu, meine Freude"
2917 composer = "J S Bach"
2919 keyTime = { \key c \minor \time 4/4 }
2920 ManualOneVoiceOneMusic = \relative g' {
2924 ManualOneVoiceTwoMusic = \relative c' {
2925 ees16 d ees8~ 16 f ees d c8 d~ d c~ |
2926 8 c4 b8 c8. g16 c b c d |
2928 ManualTwoMusic = \relative c' {
2929 c16 b c8~ 16 b c g a8 g~ 16 g aes ees |
2930 f16 ees f d g aes g f ees d ees8~ 16 f ees d |
2932 PedalOrganMusic = \relative c {
2933 r8 c16 d ees d ees8~ 16 a, b g c b c8 |
2934 r16 g ees f g f g8 c,2 |
2938 << % PianoStaff and Pedal Staff must be simultaneous
2940 \new Staff = "ManualOne" <<
2941 \keyTime % set key and time signature
2945 \ManualOneVoiceOneMusic
2949 \ManualOneVoiceTwoMusic
2951 >> % end ManualOne Staff context
2952 \new Staff = "ManualTwo" \with {
2953 \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
2960 >> % end ManualTwo Staff context
2961 >> % end PianoStaff context
2962 \new Staff = "PedalOrgan" <<
2968 >> % end PedalOrgan Staff context
2970 } % end Score context
2977 @node Saving typing with variables and functions
2978 @subsection Saving typing with variables and functions
2983 By this point, you've seen this kind of thing:
2985 @lilypond[quote,verbatim,ragged-right]
2986 hornNotes = \relative c'' { c4 b dis c }
2995 You may even realize that this could be useful in minimalist music:
2997 @lilypond[quote,verbatim,ragged-right]
2998 fragmentA = \relative c'' { a4 a8. b16 }
2999 fragmentB = \relative c'' { a8. gis16 ees4 }
3001 violin = \new Staff {
3002 \fragmentA \fragmentA |
3003 \fragmentB \fragmentA |
3013 However, you can also use these variables (also known as
3014 macros, or user-defined commands) for tweaks:
3016 @c TODO Avoid padtext - not needed with skylining
3017 @lilypond[quote,verbatim,ragged-right]
3018 dolce = \markup { \italic \bold dolce }
3020 padText = { \once \override TextScript.padding = #5.0 }
3022 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
3025 violin = \relative c'' {
3027 c4._\dolce b8 a8 g a b |
3029 c4.^"hi there!" d8 e' f g d |
3030 c,4.\fthenp b8 c4 c-. |
3038 \layout { ragged-right = ##t }
3042 These variables are obviously useful for saving
3043 typing. But they're worth considering even if you
3044 only use them once -- they reduce complexity. Let's
3045 look at the previous example without any
3046 variables. It's a lot harder to read, especially
3050 violin = \relative c'' @{
3052 c4._\markup @{ \italic \bold dolce @} b8 a8 g a b |
3053 \once \override TextScript.padding = #5.0
3054 c4.^"hi there!" d8 e' f g d |
3056 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p
3063 @c TODO Replace the following with a better example -td
3064 @c Skylining handles this correctly without padText
3066 So far we've seen static substitution -- when LilyPond
3067 sees @code{\padText}, it replaces it with the stuff that
3068 we've defined it to be (ie the stuff to the right of
3071 LilyPond can handle non-static substitution, too (you
3072 can think of these as functions).
3074 @lilypond[quote,verbatim,ragged-right]
3076 #(define-music-function
3077 (parser location padding)
3080 \once \override TextScript.padding = #padding
3084 c4^"piu mosso" b a b |
3086 c4^"piu mosso" d e f |
3088 c4^"piu mosso" fis a g |
3092 Using variables is also a good way to reduce work if the
3093 LilyPond input syntax changes (see
3094 @rprogram{Updating files with convert-ly}). If
3095 you have a single definition (such as @code{\dolce}) for all your
3096 input files (see @ref{Style sheets}), then if the syntax changes, you
3097 only need to update your single @code{\dolce} definition,
3098 instead of making changes throughout every @file{.ly} file.
3101 @node Scores and parts
3102 @subsection Scores and parts
3104 In orchestral music, all notes are printed twice. Once in a part for
3105 the musicians, and once in a full score for the conductor. Variables can
3106 be used to avoid double work. The music is entered once, and stored in
3107 a variable. The contents of that variable is then used to generate
3108 both the part and the full score.
3110 It is convenient to define the notes in a special file. For example,
3111 suppose that the file @file{horn-music.ly} contains the following part
3112 of a horn/@/bassoon duo
3115 hornNotes = \relative c @{
3117 r4 f8 a | cis4 f | e4 d |
3122 Then, an individual part is made by putting the following in a file
3125 \include "horn-music.ly"
3128 instrument = "Horn in F"
3132 \transpose f c' \hornNotes
3139 \include "horn-music.ly"
3143 substitutes the contents of @file{horn-music.ly} at this position in
3144 the file, so @code{hornNotes} is defined afterwards. The command
3145 @code{\transpose f@tie{}c'} indicates that the argument, being
3146 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
3147 @code{f} is denoted by notated @code{c'}, which corresponds with the
3148 tuning of a normal French Horn in@tie{}F. The transposition can be seen
3149 in the following output
3151 @lilypond[quote,ragged-right]
3152 \transpose f c' \relative c {
3154 r4 f8 a | cis4 f | e4 d |
3158 In ensemble pieces, one of the voices often does not play for many
3159 measures. This is denoted by a special rest, the multi-measure
3160 rest. It is entered with a capital @code{R} followed by a duration
3161 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
3162 etc.). By multiplying the
3163 duration, longer rests can be constructed. For example, this rest
3164 takes 3@tie{}measures in 2/4 time
3170 When printing the part, multi-rests
3171 must be condensed. This is done by setting a run-time variable
3174 \set Score.skipBars = ##t
3178 This command sets the property @code{skipBars} in the
3179 @code{Score} context to true (@code{##t}). Prepending the rest and
3180 this option to the music above, leads to the following result
3182 @lilypond[quote,ragged-right]
3183 \transpose f c' \relative c {
3185 \set Score.skipBars = ##t
3187 r4 f8 a | cis4 f | e4 d |
3192 The score is made by combining all of the music together. Assuming
3193 that the other voice is in @code{bassoonNotes} in the file
3194 @file{bassoon-music.ly}, a score is made with
3197 \include "bassoon-music.ly"
3198 \include "horn-music.ly"
3201 \new Staff \hornNotes
3202 \new Staff \bassoonNotes
3209 @lilypond[quote,ragged-right]
3215 r4 f8 a | cis4 f | e4 d |
3220 r4 d,8 f | gis4 c | b4 bes |
3221 a8 e f4 | g4 d | gis4 f |