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{...compound music expression...} % 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 just one music expression,
129 and this must appear immediately after the @code{\score} command.
130 Remember that a music expression could be anything from a single
131 note to a huge compound expression like
136 @var{...insert the whole score of a Wagner opera in here...}
142 Since everything is inside @code{@{ ... @}}, it counts
143 as one music expression.
145 As we saw previously, the @code{\score} block can contain other
168 Note that these three commands -- @code{\header}, @code{\layout} and
169 @code{\midi} -- are special: unlike many other commands which begin
170 with a backward slash (@code{\}) they are @emph{not} music expressions
171 and are not part of any music expression. So they may be placed
172 inside a @code{\score} block or outside it. In fact, these commands
173 are commonly placed outside the @code{\score} block -- for example,
174 @code{\header} is often placed above the @code{\score} command, as the
175 example at the beginning of this section shows.
177 Two more commands you have not previously seen are
178 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
179 shown they will cause LilyPond to produce a printed output and a
180 MIDI output respectively. They are described fully in the
181 Notation Reference -- @ruser{Score layout}, and
182 @ruser{Creating MIDI files}.
184 @cindex scores, multiple
185 @cindex book block, implicit
186 @cindex implicit book block
190 You may code multiple @code{\score} blocks. Each will be
191 treated as a separate score, but they will be all combined into
192 a single output file. A @code{\book} command is not necessary
193 -- one will be implicitly created. However, if you would like
194 separate output files from one @file{.ly} file then the
195 @code{\book} command should be used to separate the different
196 sections: each @code{\book} block will produce a
197 separate output file.
201 Every @code{\book} block creates a separate output file (e.g., a
202 PDF file). If you haven't explicitly added one, LilyPond wraps
203 your entire input code in a @code{\book} block implicitly.
205 Every @code{\score} block is a separate chunk of music within a
208 @cindex layout block, effect of location
210 Every @code{\layout} block affects the @code{\score} or
211 @code{\book} block in which it appears -- i.e., a @code{\layout}
212 block inside a @code{\score} block affects only that @code{\score}
213 block, but a @code{\layout} block outside of a @code{\score} block
214 (and thus in a @code{\book} block, either explicitly or
215 implicitly) will affect every @code{\score} in that @code{\book}.
217 For details see @ruser{Multiple scores in a book}.
221 Another great shorthand is the ability to define variables, as
222 shown in @ref{Organizing pieces with variables}. All the
226 melody = \relative c' @{
235 When LilyPond looks at this file, it takes the value of
236 @code{melody} (everything after the equals sign) and inserts it
237 whenever it sees @code{\melody}. There's nothing special about
238 the name -- it could be @code{melody}, @code{global},
239 @code{keyTime}, @code{pianorighthand}, or something else.
240 Remember that you can use almost any name you like as long as it
241 contains just alphabetic characters and is distinct from LilyPond
242 command names. For more details, see @ref{Saving typing with
243 variables and functions}. The exact limitations on variable names
244 are detailed in @ruser{File structure}.
248 For a complete definition of the input format, see
249 @ruser{File structure}.
252 @node Score is a (single) compound musical expression
253 @subsection Score is a (single) compound musical expression
258 @cindex contents of a score block
259 @cindex score block, contents of
260 @cindex compound music expression
261 @cindex music expression, compound
263 We saw the general organization of LilyPond input files in the
264 previous section, @ref{Introduction to the LilyPond file structure}.
265 But we seemed to skip over the most important part: how do we figure
266 out what to write after @code{\score}?
268 We didn't skip over it at all. The big mystery is simply that
269 there @emph{is} no mystery. This line explains it all:
272 @emph{A @code{\score} block must begin with a compound music expression.}
276 To understand what is meant by a music expression and a compound
277 music expression, you may find it useful to review the tutorial,
278 @ref{Music expressions explained}. In that section, we saw how to
279 build big music expressions from small pieces -- we started from
280 notes, then chords, etc. Now we're going to start from a big
281 music expression and work our way down. For simplicity, we'll use
282 just a singer and piano in our example. We don't need a
283 @code{StaffGroup} for this ensemble, which simply groups a number
284 of staves together with a bracket at the left, but we do need
285 staves for a singer and a piano, though.
290 \new Staff = "singer" <<
292 \new PianoStaff = "piano" <<
299 Here we have given names to the staves -- @qq{singer} and
300 @qq{piano}. This is not essential here, but it is a useful habit
301 to cultivate so that you can see at a glance what each stave is
304 Remember that we use @code{<< ... >>} instead of @code{@{ ... @}} to
305 show simultaneous music. This causes the vocal part and piano part
306 to appear one above the other in the score. The @code{<< ... >>}
307 construct would not be necessary for the Singer staff in the example
308 above if it were going to contain only one sequential music
309 expression, but @code{<< ... >>} rather than braces is necessary if
310 the music in the Staff is to contain two or more simultaneous
311 expressions, e.g. two simultaneous Voices, or a Voice with lyrics.
312 We're going to have a voice with lyrics, so angle brackets are
313 required. We'll add some real music later; for now let's just put
314 in some dummy notes and lyrics. If you've forgotten how to add lyrics
315 you may wish to review @code{\addlyrics} in @ref{Setting simple songs}.
317 @lilypond[verbatim,quote,ragged-right]
320 \new Staff = "singer" <<
321 \new Voice = "vocal" { c'1 }
324 \new PianoStaff = "piano" <<
325 \new Staff = "upper" { c'1 }
326 \new Staff = "lower" { c'1 }
333 Now we have a lot more details. We have the singer's staff: it
334 contains a @code{Voice} (in LilyPond, this term refers to a set of
335 notes, not necessarily vocal notes -- for example, a violin
336 generally plays one voice) and some lyrics. We also have a piano
337 staff: it contains an upper staff (right hand) and a lower staff
338 (left hand), although the lower staff has yet to be given a bass
341 At this stage, we could start filling in notes. Inside the curly
342 braces next to @code{\new Voice = "vocal"}, we could start writing
350 But if we did that, the @code{\score} section would get pretty
351 long, and it would be harder to understand what was happening. So
352 let's use variables instead. These were introduced at the end
353 of the previous section, remember? To ensure the contents of the
354 @code{text} variable are interpreted as lyrics we preface them with
355 @code{\lyricmode}. Like @code{\addlyrics}, this switches the input
356 mode to lyrics. Without that, LilyPond would try to interpret the
357 contents as notes, which would generate errors. (Several other
358 input modes are available, see @ruser{Input modes}.)
360 So, adding a few notes and a bass clef for the left hand, we now
361 have a piece of real music:
363 @lilypond[verbatim,quote,ragged-right]
364 melody = \relative c'' { r4 d8\noBeam g, c4 r }
365 text = \lyricmode { And God said, }
366 upper = \relative c'' { <g d g,>2~ <g d g,> }
367 lower = \relative c { b2 e }
371 \new Staff = "singer" <<
372 \new Voice = "vocal" { \melody }
375 \new PianoStaff = "piano" <<
376 \new Staff = "upper" { \upper }
377 \new Staff = "lower" {
387 When writing (or reading) a @code{\score} section, just take it
388 slowly and carefully. Start with the outer level, then work on
389 each smaller level. It also really helps to be strict with
390 indentation -- make sure that each item on the same level starts
391 on the same horizontal position in your text editor.
395 Notation Reference: @ruser{Structure of a score}.
398 @node Nesting music expressions
399 @subsection Nesting music expressions
401 @cindex staves, temporary
402 @cindex temporary staves
405 It is not essential to declare all staves at the beginning; they may
406 be introduced temporarily at any point. This is particularly useful
407 for creating ossia sections -- see @rglos{ossia}. Here is a simple
408 example showing how to introduce a new staff temporarily for the
409 duration of three notes:
411 @lilypond[verbatim,quote,ragged-right]
428 Note that the size of the clef is the same as a clef printed
429 following a clef change -- slightly smaller than the clef
430 at the beginning of the line. This is usual for clefs printed
431 in the middle of a line.
433 @cindex staff, positioning
435 The ossia section may be placed above the staff
438 @lilypond[verbatim,quote,ragged-right]
439 \new Staff = "main" {
446 alignAboveContext = #"main"
454 This example uses @code{\with}, which will be explained more
455 fully later. It is a means of modifying the default behavior
456 of a single Staff. Here it says that the new staff should be
457 placed above the staff called @qq{main} instead of the default
458 position which is below.
462 Ossia are often written without clef and without
463 time signature and are usually in a smaller font.
464 These require further commands which
465 have not yet been introduced. See @ref{Size of objects},
466 and @ruser{Ossia staves}.
469 @node On the un-nestedness of brackets and ties
470 @subsection On the un-nestedness of brackets and ties
472 @cindex brackets, nesting
473 @cindex bracket types
474 @cindex brackets, enclosing vs. marking
476 You have already met a number of different types of bracket and
477 bracket-like constructs in writing the input file to LilyPond.
478 These obey different rules which can be confusing at first.
479 Let's first review the different types of brackets and bracket-like
482 @c attempt to force this onto a new page
484 @multitable @columnfractions .3 .7
485 @headitem Bracket Type
487 @item @code{@{ .. @}}
488 @tab Encloses a sequential segment of music
490 @tab Encloses the notes of a chord
491 @item @code{<< .. >>}
492 @tab Encloses simultaneous music expressions
494 @tab Marks the start and end of a slur
495 @item @code{\( .. \)}
496 @tab Marks the start and end of a phrasing slur
498 @tab Marks the start and end of a manual beam
501 To these we should add other constructs which generate lines
502 between or across notes: ties (marked by a tilde, @code{~}),
503 tuplets written as @code{\times x/y @{..@}}, and grace notes
504 written as @code{\grace@{..@}}.
506 Outside LilyPond, the conventional use of brackets requires the
507 different types to be properly nested, like this, @code{<< [ @{ ( .. )
508 @} ] >>}, with the closing brackets being encountered in exactly the
509 opposite order to the opening brackets. This @strong{is} a
510 requirement for the three types of bracket described by the word
511 @q{Encloses} in the table above -- they must nest properly. However,
512 the remaining bracket-like constructs, described with the word
513 @q{Marks} in the table above together with ties and tuplets, do
514 @strong{not} have to nest properly with any of the brackets or
515 bracket-like constructs. In fact, these are not brackets in
516 the sense that they enclose something -- they are simply markers to
517 indicate where something starts and ends.
519 So, for example, a phrasing slur can start before a manually
520 inserted beam and end before the end of the beam -- not very
521 musical, perhaps, but possible:
523 @lilypond[quote,verbatim,ragged-right,relative=2]
524 g8\( a b[ c b\) a] g4
527 In general, different kinds of brackets, bracket-like constructs,
528 and those implied by tuplets, ties and grace notes, may be mixed
529 freely. This example shows a beam extending into a tuplet (line 1),
530 a slur extending into a tuplet (line 2), a beam and a slur
531 extending into a tuplet, a tie crossing two tuplets, and a
532 phrasing slur extending out of a tuplet (lines 3 and 4).
534 @lilypond[quote,verbatim,ragged-right,relative=1]
535 r16[ g \times 2/3 { r16 e'8] }
536 g,16( a \times 2/3 { b16 d) e }
537 g,8[( a \times 2/3 { b8 d) e~] } |
538 \times 4/5 { e32\( a, b d e } a4.\)
542 @node Voices contain music
543 @section Voices contain music
545 Singers need voices to sing, and so does LilyPond.
546 The actual music for all instruments in a score
547 is contained in Voices -- the most fundamental
548 of all LilyPond's concepts.
551 * I'm hearing Voices::
552 * Explicitly instantiating voices::
553 * Voices and vocals::
556 @node I'm hearing Voices
557 @subsection I'm hearing Voices
561 @cindex multiple voices
562 @cindex voices, multiple
563 @cindex Voice context
564 @cindex context, Voice
565 @cindex simultaneous music
566 @cindex music, simultaneous
567 @cindex concurrent music
568 @cindex music, concurrent
569 @cindex voices vs. chords
570 @cindex chords vs. voices
572 The lowest, most fundamental or innermost layers in a LilyPond
573 score are called @q{Voice contexts} or just @q{Voices} for short.
574 Voices are sometimes called @q{layers} in other notation
577 In fact, a Voice layer or context is the only one which can contain
578 music. If a Voice context is not explicitly declared one is created
579 automatically, as we saw at the beginning of this chapter. Some
580 instruments such as an Oboe can play only one note at a time. Music
581 written for such instruments is monophonic and requires just a single
582 voice. Instruments which can play more than one note at a time like
583 the piano will often require multiple voices to encode the different
584 concurrent notes and rhythms they are capable of playing.
586 A single voice can contain many notes in a chord, of course,
587 so when exactly are multiple voices needed? Look first at
588 this example of four chords:
590 @lilypond[quote,verbatim,ragged-right,relative=1]
592 <d g>4 <d fis> <d a'> <d g>
595 This can be expressed using just the single angle bracket chord
596 symbols, @code{< ... >}, and for this just a single voice is
597 needed. But suppose the F-sharp were actually an eighth-note
598 followed by an eighth-note G, a passing note on the way to the A?
599 Now we have two notes which start at the same time but have
600 different durations: the quarter-note D and the eighth-note
601 F-sharp. How are these to be coded? They cannot be written as
602 a chord because all the notes in a chord must have the same
603 duration. And they cannot be written as two sequential notes
604 as they need to start at the same time. This is when two
607 Let us see how this is done in LilyPond input syntax.
612 The easiest way to enter fragments with more than one voice on a
613 staff is to enter each voice as a sequence (with @code{@{...@}}),
614 and combine them simultaneously with angle brackets, @code{<<...>>}.
615 The fragments must also be separated with double backward slashes,
616 @code{\\}, to place them in separate voices. Without these, the
617 notes would be entered into a single voice, which would usually
618 cause errors. This technique is particularly suited to pieces of
619 music which are largely monophonic with occasional short sections
622 Here's how we split the chords above into two voices and add both
623 the passing note and a slur:
625 @lilypond[quote,verbatim,ragged-right,relative=2]
627 % Voice "1" Voice "2"
628 << { g4 fis8( g) a4 g } \\ { d4 d d d } >>
631 Notice how the stems of the second voice now point down.
633 Here's another simple example:
635 @lilypond[quote,verbatim,ragged-right,relative=2]
637 % Voice "1" Voice "2"
638 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
639 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
640 << { 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,relative=2]
665 @cindex voices, naming
666 @cindex voices crossing brackets
667 @cindex slurs crossing brackets
668 @cindex ties crossing brackets
670 This example has just two voices, but the same construct may be
671 used to encode three or more voices by adding more back-slash
674 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
675 The first contexts set the @emph{outer} voices, the highest
676 voice in context @code{"1"} and the lowest voice in context
677 @code{"2"}. The inner voices go in contexts @code{"3"} and
678 @code{"4"}. In each of these contexts, the vertical direction
679 of slurs, stems, ties, dynamics etc., is set appropriately.
681 @lilypond[quote,verbatim]
682 \new Staff \relative c' {
685 % Voice "1" Voice "2" Voice "3"
686 << { g4 f e } \\ { r8 e4 d c8~ } >> |
687 << { d2 e } \\ { c8 b16 a b8 g~ g2 } \\ { s4 b c2 } >> |
691 These voices are all separate from the main voice that contains
692 the notes just outside the @code{<< .. >>} construct. Let's call
693 this the @emph{simultaneous construct}. Slurs and ties may only
694 connect notes within the same voice, so slurs and ties cannot go
695 into or out of a simultaneous construct. Conversely,
696 parallel voices from separate simultaneous constructs on the same
697 staff are the same voice. Other voice-related properties also
698 carry across simultaneous constructs. Here is the same example,
699 with different colors and note heads for each voice. Note that
700 changes in one voice do not affect other voices, but they do
701 persist in the same voice later. Note also that tied notes may be
702 split across the same voices in two constructs, shown here in the
705 @lilypond[quote,verbatim]
706 \new Staff \relative c' {
725 { c8 b16 a b8 g~ g2 }
735 @funindex \voiceOneStyle
736 @funindex \voiceTwoStyle
737 @funindex \voiceThreeStyle
738 @funindex \voiceFourStyle
739 @funindex \voiceNeutralStyle
741 The commands @code{\voiceXXXStyle} are mainly intended for use in
742 educational documents such as this one. They modify the color
743 of the note head, the stem and the beams, and the style of the
744 note head, so that the voices may be easily distinguished.
745 Voice one is set to red diamonds, voice two to blue triangles,
746 voice three to green crossed circles, and voice four (not used
747 here) to magenta crosses; @code{\voiceNeutralStyle} (also not
748 used here) reverts the style back to the default.
749 We shall see later how commands like these may be created by the
751 See @ref{Visibility and color of objects} and
752 @ref{Using variables for tweaks}.
754 @cindex polyphony and relative note entry
755 @cindex relative note entry and polyphony
757 Polyphony does not change the relationship of notes within a
758 @code{\relative} block. Each note is still calculated relative to
759 the note immediately preceding it, or to the first note of the
760 preceding chord. So in
763 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
767 @code{noteB} is relative to @code{noteA} @*
768 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
769 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
771 @code{noteE} is relative to @code{noteD}, not @code{noteA}.
773 An alternative way, which may be clearer if the notes in the
774 voices are widely separated, is to place a @code{\relative}
775 command at the start of each voice:
778 \relative c' @{ noteA ... @}
780 \relative c'' @{ < noteB noteC > ... @}
782 \relative g' @{ noteD ... @}
784 \relative c' @{ noteE ... @}
787 Let us finally analyze the voices in a more complex piece of music.
788 Here are the notes from the first two bars of the second of Chopin's
789 Deux Nocturnes, Op 32. This example will be used at later stages in
790 this and the next chapter to illustrate several techniques for
791 producing notation, so please ignore for now anything in the
792 underlying code which looks mysterious and concentrate just on the
793 music and the voices -- the complications will all be explained in
796 @c The following should appear as music without code
797 @lilypond[quote,ragged-right]
798 \new Staff \relative c'' {
804 % Ignore these for now - they are explained in Ch 4
805 \once \override NoteColumn #'ignore-collision = ##t
807 \once \override NoteColumn #'force-hshift = #0.5
813 \override NoteColumn #'force-hshift = #0
821 The direction of the stems is often used to indicate the continuity of
822 two simultaneous melodic lines. Here the stems of the highest notes
823 are all pointing up and the stems of the lower notes are all pointing
824 down. This is the first indication that more than one voice is
827 But the real need for multiple voices arises when notes
828 which start at the same time have different durations.
829 Look at the notes which start at beat three in the first
830 bar. The A-flat is a dotted quarter note, the F is a
831 quarter note and the D-flat is a half note. These
832 cannot be written as a chord as all the notes in a chord
833 must have the same duration. Neither can they be written
834 as sequential notes, as they must start at the same time.
835 This section of the bar requires three voices, and the
836 normal practice would be to write the whole bar as three
837 voices, as shown below, where we have used different note heads
838 and colors for the three voices. Again, the code behind this
839 example will be explained later, so ignore anything you do
842 @c The following should appear as music without code
843 @c The three voice styles should be defined in -init
844 @lilypond[quote,ragged-right]
845 \new Staff \relative c'' {
854 % Ignore these for now - they are explained in Ch 4
855 \once \override NoteColumn #'ignore-collision = ##t
857 \once \override NoteColumn #'force-hshift = #0.5
860 \\ % No Voice three (we want stems down)
863 \override NoteColumn #'force-hshift = #0
872 Let us try to encode this music from scratch. As we
873 shall see, this encounters some difficulties. We begin as
874 we have learnt, using the @code{<< \\ >>} construct to
875 enter the music of the first bar in three voices:
877 @lilypond[quote,verbatim,ragged-right]
878 \new Staff \relative c'' {
881 { c2 aes4. bes8 } \\ { <ees, c>2 des } \\ { aes'2 f4 fes }
888 @cindex voices and stem directions
889 @cindex stem directions and voices
892 The stem directions are automatically assigned with the
893 odd-numbered voices taking upward stems and the even-numbered
894 voices downward ones. The stems for voices 1 and 2 are right,
895 but the stems in voice 3 should go down in this particular piece
896 of music. We can correct this by skipping voice three
897 and placing the music in voice four. This is done by simply
898 adding another pair of @code{\\}.
900 @lilypond[quote,verbatim,ragged-right]
901 \new Staff \relative c'' {
907 \\ % Omit Voice three
916 We see that this fixes the stem direction, but the horizontal
917 placement of notes is not what we want. LilyPond shifts the
918 inner notes when they or their stems would collide with outer
919 voices, but this is not appropriate for piano music. In other
920 situations, the shifts LilyPond applies might fail to clear
921 the collisions. LilyPond provides several ways to adjust the
922 horizontal placing of notes. We are not quite ready yet to see
923 how to correct this, so we shall leave this problem until a
924 later section --- see the @code{force-hshift} property in
925 @ref{Fixing overlapping notation}.
927 @warning{Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be
928 created @q{across} voices.}
932 Notation Reference: @ruser{Multiple voices}.
935 @node Explicitly instantiating voices
936 @subsection Explicitly instantiating voices
942 @funindex \voiceThree
949 @cindex voice contexts, creating
951 Voice contexts can also be created manually
952 inside a @code{<< >>} block to create polyphonic music, using
953 @code{\voiceOne} @dots{} @code{\voiceFour} to indicate the required
954 directions of stems, slurs, etc. In longer scores this method
955 is clearer, as it permits the voices to be separated and to be
956 given more descriptive names.
958 Specifically, the construct @code{<< \\ >>} which we used in
959 the previous section:
964 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
974 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
975 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
979 Both of the above would produce
981 @c The following example should not display the code
982 @lilypond[ragged-right,quote]
984 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
985 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
989 @cindex voices, reverting to single
990 @cindex reverting to a single voice
992 The @code{\voiceXXX} commands set the direction of stems, slurs,
993 ties, articulations, text annotations, augmentation dots of dotted
994 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
995 make these objects point upwards, while @code{\voiceTwo} and
996 @code{\voiceFour} make them point downwards. These commands also
997 generate a horizontal shift for each voice when this is required
998 to avoid clashes of note heads. The command @code{\oneVoice}
999 reverts the settings back to the normal values for a single voice.
1001 Let us see in some simple examples exactly what effect
1002 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
1003 markup, ties, slurs, and dynamics:
1005 @lilypond[quote,ragged-right,verbatim]
1007 % Default behavior or behavior after \oneVoice
1008 c4 d8~ d e4( f | g4 a) b-> c |
1012 @lilypond[quote,ragged-right,verbatim]
1015 c4 d8~ d e4( f | g4 a) b-> c |
1017 c,4 d8~ d e4( f | g4 a) b-> c |
1021 @lilypond[quote,ragged-right,verbatim]
1024 c4 d8~ d e4( f | g4 a) b-> c |
1026 c,4 d8~ d e4( f | g4 a) b-> c |
1030 Now let's look at three different ways to notate the same passage
1031 of polyphonic music, each of which is advantageous in different
1032 circumstances, using the example from the previous section.
1034 An expression that appears directly inside a @code{<< >>} belongs
1035 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
1036 construct). This is useful when extra voices appear while the
1037 main voice is playing. Here is a more correct rendition of our
1038 example. The red diamond-shaped notes
1039 demonstrate that the main melody is now in a single voice context,
1040 permitting a phrasing slur to be drawn over them.
1042 @lilypond[quote,ragged-right,verbatim]
1043 \new Staff \relative c' {
1045 % The following notes are monophonic
1047 % Start simultaneous section of three voices
1049 % Continue the main voice in parallel
1050 { g4 f e | d2 e) | }
1051 % Initiate second voice
1053 % Set stems, etc., down
1055 r8 e4 d c8~ | c8 b16 a b8 g~ g2 |
1057 % Initiate third voice
1059 % Set stems, etc, up
1067 @cindex nesting music expressions
1068 @cindex nesting simultaneous constructs
1069 @cindex nesting voices
1070 @cindex voices, temporary
1071 @cindex voices, nesting
1073 More deeply nested polyphony constructs are possible, and if a
1074 voice appears only briefly this might be a more natural way to
1077 @lilypond[quote,ragged-right,verbatim]
1078 \new Staff \relative c' {
1081 { g4 f e | d2 e) | }
1086 { c8 b16 a b8 g~ g2 | }
1097 @cindex spacing notes
1099 This method of nesting new voices briefly is useful
1100 when only small sections of the music
1101 are polyphonic, but when the whole staff is largely polyphonic
1102 it can be clearer to use multiple voices throughout, using
1103 spacing notes to step over sections where the voice is silent,
1106 @lilypond[quote,ragged-right,verbatim]
1107 \new Staff \relative c' <<
1108 % Initiate first voice
1111 c16^( d e f g4 f e | d2 e) |
1113 % Initiate second voice
1115 % Set stems, etc, down
1117 s4 r8 e4 d c8~ | c8 b16 a b8 g~ g2 |
1119 % Initiate third voice
1121 % Set stems, etc, up
1128 @subsubheading Note columns
1131 @cindex note collisions
1132 @cindex collisions, notes
1133 @cindex shift commands
1140 @funindex \shiftOnnn
1143 Closely spaced notes in a chord, or notes occurring at the same
1144 time in different voices, are arranged in two, occasionally more,
1145 columns to prevent the note heads overlapping. These are called
1146 note columns. There are separate columns for each voice, and
1147 the currently specified voice-dependent shift is applied to the
1148 note column if there would otherwise be a collision. This can
1149 be seen in the example above. In bar 2 the C in voice two is
1150 shifted to the right relative to the D in voice one, and in the
1151 final chord the C in voice three is also shifted to the right
1152 relative to the other notes.
1154 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1155 @code{\shiftOff} commands specify the degree to which notes and
1156 chords of the voice should be shifted if a collision
1157 would otherwise occur. By default, the outer voices (normally
1158 voices one and two) have @code{\shiftOff} specified, while the
1159 inner voices (three and four) have @code{\shiftOn} specified.
1160 When a shift is applied, voices one and three are shifted to
1161 the right and voices two and four to the left.
1163 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1164 levels which may be specified temporarily to resolve collisions
1165 in complex situations -- see @ref{Real music example}.
1167 A note column can contain just one note (or chord) from a voice
1168 with stems up and one note (or chord) from a voice with stems
1169 down. If notes from two voices which have their stems in the
1170 same direction are placed at the same position and both voices
1171 have no shift or the same shift specified, the error message
1172 @qq{Too many clashing note columns} will be produced.
1176 Notation Reference: @ruser{Multiple voices}.
1179 @node Voices and vocals
1180 @subsection Voices and vocals
1182 Vocal music presents a special difficulty: we need to combine two
1183 expressions -- notes and lyrics.
1185 @funindex \new Lyrics
1189 @cindex Lyrics context, creating
1190 @cindex lyrics, linking to voice
1192 You have already seen the @code{\addlyrics@{@}} command, which
1193 handles simple scores well. However, this technique is
1194 quite limited. For more complex music, you must introduce the
1195 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1197 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1198 name assigned to the Voice.
1200 @lilypond[quote,verbatim]
1202 \new Voice = "one" {
1206 c4 b8. a16 | g4. f8 | e4 d | c2 |
1209 \new Lyrics \lyricsto "one" {
1210 No more let | sins and | sor -- rows | grow. |
1215 Note that the lyrics must be linked to a @code{Voice} context,
1216 @emph{not} a @code{Staff} context. This is a case where it is
1217 necessary to create @code{Staff} and @code{Voice} contexts
1220 @cindex lyrics and beaming
1221 @cindex beaming and lyrics
1222 @funindex \autoBeamOff
1223 @funindex autoBeamOff
1225 The automatic beaming which LilyPond uses by default works well
1226 for instrumental music, but not so well for music with lyrics,
1227 where beaming is either not required at all or is used to indicate
1228 melismata in the lyrics. In the example above we use the command
1229 @code{\autoBeamOff} to turn off the automatic beaming.
1231 @funindex \new ChoirStaff
1232 @funindex ChoirStaff
1233 @funindex \lyricmode
1235 @cindex vocal score structure
1238 Let us reuse the earlier example from Judas Maccabæus to
1239 illustrate this more flexible technique. We first recast
1240 it to use variables so the music and lyrics can be separated
1241 from the staff structure. We also introduce a ChoirStaff
1242 bracket. The lyrics themselves must be introduced with
1243 @code{\lyricmode} to ensure they are interpreted as lyrics
1246 @lilypond[quote,verbatim]
1247 global = { \key f \major \time 6/8 \partial 8 }
1249 SopOneMusic = \relative c'' {
1250 c8 | c8([ bes)] a a([ g)] f | f'4. b, | c4.~ c4
1252 SopOneLyrics = \lyricmode {
1253 Let | flee -- cy flocks the | hills a -- dorn, __
1255 SopTwoMusic = \relative c' {
1256 r8 | r4. r4 c8 | a'8([ g)] f f([ e)] d | e8([ d)] c bes'
1258 SopTwoLyrics = \lyricmode {
1259 Let | flee -- cy flocks the | hills a -- dorn,
1265 \new Voice = "SopOne" {
1269 \new Lyrics \lyricsto "SopOne" {
1274 \new Voice = "SopTwo" {
1278 \new Lyrics \lyricsto "SopTwo" {
1286 This is the basic structure of all vocal scores. More staves may be
1287 added as required, more voices may be added to the staves, more verses
1288 may be added to the lyrics, and the variables containing the music can
1289 easily be placed in separate files should they become too long.
1291 @cindex hymn structure
1292 @cindex SATB structure
1293 @cindex vocal scores with multiple verses
1294 @cindex multiple vocal verses
1295 @cindex verses, multiple vocal
1297 Here is an example of the first line of a hymn with four
1298 verses, set for SATB. In this case the words for all four
1299 parts are the same. Note how we use variables to separate the
1300 music notation and words from the staff structure. See too
1301 how a variable, which we have chosen to call @q{keyTime}, is used
1302 to hold several commands for use within the two staves. In other
1303 examples this is often called @q{global}.
1305 @lilypond[quote,verbatim]
1306 keyTime = { \key c \major \time 4/4 \partial 4 }
1308 SopMusic = \relative c' { c4 | e4. e8 g4 g | a4 a g }
1309 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f4 f e }
1310 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1311 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1314 \lyricmode { E -- | ter -- nal fa -- ther, | strong to save, }
1316 \lyricmode { O | Christ, whose voice the | wa -- ters heard, }
1318 \lyricmode { O | Ho -- ly Spi -- rit, | who didst brood }
1320 \lyricmode { O | Tri -- ni -- ty of | love and pow'r }
1326 \new Voice = "Sop" { \voiceOne \keyTime \SopMusic }
1327 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1328 \new Lyrics \lyricsto "Sop" { \VerseOne }
1329 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1330 \new Lyrics \lyricsto "Sop" { \VerseThree }
1331 \new Lyrics \lyricsto "Sop" { \VerseFour }
1335 \new Voice = "Tenor" { \voiceOne \keyTime \TenorMusic }
1336 \new Voice = "Bass" { \voiceTwo \BassMusic }
1344 Notation Reference: @ruser{Vocal music}.
1347 @node Contexts and engravers
1348 @section Contexts and engravers
1350 Contexts and engravers have been mentioned informally
1351 in earlier sections; we now must look at
1352 these concepts in more detail, as they are important
1353 in the fine-tuning of LilyPond output.
1357 * Contexts explained::
1358 * Creating contexts::
1359 * Engravers explained::
1360 * Modifying context properties::
1361 * Adding and removing engravers::
1364 @node Contexts explained
1365 @subsection Contexts explained
1367 @cindex contexts explained
1369 When music is printed, many notational elements which do not
1370 appear explicitly in the input file must be added to the
1371 output. For example, compare the input and output of the
1374 @lilypond[quote,verbatim,relative=2]
1375 cis4 cis2. | a4 a2. |
1378 The input is rather sparse, but in the output, bar lines,
1379 accidentals, clef, and time signature have been added. When
1380 LilyPond @emph{interprets} the input the musical information
1381 is parsed from left to right, similar to the way a performer
1382 reads the score. While reading the input, the program remembers
1383 where measure boundaries are, and which pitches require explicit
1384 accidentals. This information must be held on several levels.
1385 For example, an accidental affects only a single staff, while
1386 a bar line must be synchronized across the entire score.
1388 Within LilyPond, these rules and bits of information are grouped in
1389 @emph{Contexts}. We have already introduced the @code{Voice} context.
1390 Others are the @code{Staff} and @code{Score} contexts. Contexts are
1391 hierarchical to reflect the hierarchical nature of a musical score.
1392 For example: a @code{Staff} context can contain many @code{Voice}
1393 contexts, and a @code{Score} context can contain many @code{Staff}
1397 @sourceimage{context-example,5cm,,}
1400 Each context has the responsibility for enforcing some notation rules,
1401 creating some notation objects and maintaining the associated
1402 properties. For example, the @code{Voice} context may introduce an
1403 accidental and then the @code{Staff} context maintains the rule to
1404 show or suppress the accidental for the remainder of the measure.
1406 As another example, the synchronization of bar lines is, by default,
1407 handled in the @code{Score} context.
1408 However, in some music we may not want the bar lines to be
1409 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1410 In such cases, we must modify the default settings of the
1411 @code{Score} and @code{Staff} contexts.
1413 For very simple scores, contexts are created implicitly, and you need
1414 not be aware of them. For larger pieces, such as anything with more
1415 than one staff, they must be
1416 created explicitly to make sure that you get as many staves as you
1417 need, and that they are in the correct order. For typesetting pieces
1418 with specialized notation, it is usual to modify existing, or
1419 even to define totally new, contexts.
1421 In addition to the @code{Score,} @code{Staff} and
1422 @code{Voice} contexts there are contexts which fit between
1423 the score and staff levels to control staff groups, such as the
1424 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1425 are also alternative staff and voice contexts, and contexts for
1426 lyrics, percussion, fret boards, figured bass, etc.
1428 The names of all context types are formed from one or more
1429 words, each word being capitalized and joined immediately to the
1430 preceding word with no hyphen or underscore, e.g.,
1431 @code{GregorianTranscriptionStaff}.
1435 Notation Reference: @ruser{Contexts explained}.
1438 @node Creating contexts
1439 @subsection Creating contexts
1443 @cindex new contexts
1444 @cindex creating contexts
1445 @cindex contexts, creating
1447 In an input file a score block, introduced with a @code{\score}
1448 command, contains a single music expression and an associated
1449 output definition (either a @code{\layout} or a @code{\midi} block).
1450 The @code{Score} context is usually left to be created automatically
1451 when the interpretation of that music expression starts.
1453 For scores with only one voice and one staff, the @code{Voice} and
1454 @code{Staff} contexts may also be left to be created automatically,
1455 but for more complex scores it is necessary to create them by hand.
1456 The simplest command that does this is @code{\new}. It is prepended
1457 to a music expression, for example
1460 \new @var{type} @var{music-expression}
1464 where @var{type} is a context name (like @code{Staff} or
1465 @code{Voice}). This command creates a new context, and starts
1466 interpreting the @var{music-expression} within that context.
1468 @warning{@bs{}@code{new Score} should not be used as the essential
1469 top-level @code{Score} context is created automatically when the music
1470 expression within the @bs{}@code{score} block is interpreted. Score-wide
1471 default values of context properties can be changed within the
1472 @bs{}@code{layout} block. See @ref{Modifying context properties}}
1474 You have seen many practical examples which created new
1475 @code{Staff} and @code{Voice} contexts in earlier sections, but
1476 to remind you how these commands are used in practice, here's an
1477 annotated real-music example:
1479 @lilypond[quote,verbatim,ragged-right]
1480 \score { % start of single compound music expression
1481 << % start of simultaneous staves section
1483 \new Staff { % create RH staff
1486 \new Voice { % create voice for RH notes
1487 \relative c'' { % start of RH notes
1493 \new Staff << % create LH staff; needs two simultaneous voices
1496 \new Voice { % create LH voice one
1498 \relative g { % start of LH voice one notes
1499 g8 <bes d> ees, <g c> |
1500 g8 <bes d> ees, <g c> |
1501 } % end of LH voice one notes
1502 } % end of LH voice one
1503 \new Voice { % create LH voice two
1505 \relative g { % start of LH voice two notes
1508 } % end of LH voice two notes
1509 } % end of LH voice two
1510 >> % end of LH staff
1511 >> % end of simultaneous staves section
1512 } % end of single compound music expression
1515 (Note how all the statements which open a block with either a
1516 curly bracket, @code{@{}, or double angle brackets, @code{<<},
1517 are indented by two further spaces, and the corresponding
1518 closing bracket is indented by exactly the same amount. While
1519 this is not required, following this practice will greatly
1520 reduce the number of @q{unmatched bracket} errors, and is
1521 strongly recommended. It enables the structure of the music to
1522 be seen at a glance, and any unmatched brackets will be obvious.
1523 Note too how the LH staff is created using double angle brackets
1524 because it requires two voices for its music, whereas the RH staff
1525 is created with a single music expression surrounded by curly
1526 brackets because it requires only one voice.)
1528 @cindex contexts, naming
1529 @cindex naming contexts
1531 The @code{\new} command may also give an identifying name to the
1532 context to distinguish it from other contexts of the same type,
1535 \new @var{type} = @var{id} @var{music-expression}
1538 Note the distinction between the name of the context type,
1539 @code{Staff}, @code{Voice}, etc, and the identifying name of a
1540 particular instance of that type, which can be any sequence of letters
1541 invented by the user. Digits and spaces can also be used in the
1542 identifying name, but then it has to be placed in quotes,
1543 i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
1544 The identifying name is used to
1545 refer back to that particular instance of a context. We saw this in
1546 use in the section on lyrics, see @ref{Voices and vocals}.
1550 Notation Reference: @ruser{Creating contexts}.
1553 @node Engravers explained
1554 @subsection Engravers explained
1558 Every mark on the printed output of a score produced by LilyPond
1559 is produced by an @code{Engraver}. Thus there is an engraver
1560 to print staves, one to print note heads, one for stems, one for
1561 beams, etc, etc. In total there are over 120 such engravers!
1562 Fortunately, for most scores it is not necessary to know about
1563 more than a few, and for simple scores you do not need to know
1566 Engravers live and operate in Contexts. Engravers such as the
1567 @code{Metronome_mark_engraver}, whose action and output apply to the
1568 score as a whole, operate in the highest level context -- the
1569 @code{Score} context.
1571 The @code{Clef_engraver} and @code{Key_engraver} are to be
1572 found in every @code{Staff} Context, as different staves may require
1573 different clefs and keys.
1575 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1576 in every @code{Voice} context, the lowest level context of all.
1578 Each engraver processes the particular objects associated
1579 with its function, and maintains the properties that relate
1580 to that function. These properties, like the properties
1581 associated with contexts, may be modified to change the
1582 operation of the engraver or the appearance of those elements
1583 in the printed score.
1585 Engravers all have compound names formed from words which
1586 describe their function. Just the first word is capitalized,
1587 and the remainder are joined to it with underscores. Thus
1588 the @code{Staff_symbol_engraver} is responsible for creating the
1589 lines of the staff, the @code{Clef_engraver} determines and sets
1590 the pitch reference point on the staff by drawing a clef symbol.
1592 Here are some of the most common engravers together with their
1593 function. You will see it is usually easy to guess the function
1594 from the name, or vice versa.
1596 @multitable @columnfractions .3 .7
1599 @item Accidental_engraver
1600 @tab Makes accidentals, cautionary and suggested accidentals
1605 @item Completion_heads_engraver
1606 @tab Splits notes which cross bar lines
1607 @c The old Dynamic_engraver is deprecated. -jm
1608 @item New_dynamic_engraver
1609 @tab Creates hairpins and dynamic texts
1610 @item Forbid_line_break_engraver
1611 @tab Prevents line breaks if a musical element is still active
1613 @tab Creates the key signature
1614 @item Metronome_mark_engraver
1615 @tab Engraves metronome marking
1616 @item Note_heads_engraver
1617 @tab Engraves note heads
1620 @item Staff_symbol_engraver
1621 @tab Engraves the five (by default) lines of the staff
1623 @tab Creates stems and single-stem tremolos
1624 @item Time_signature_engraver
1625 @tab Creates time signatures
1630 We shall see later how the output of LilyPond can be changed
1631 by modifying the action of Engravers.
1635 Internals reference: @rinternals{Engravers and Performers}.
1638 @node Modifying context properties
1639 @subsection Modifying context properties
1641 @cindex context properties
1642 @cindex context properties, modifying
1643 @cindex modifying context properties
1649 Contexts are responsible for holding the values of a number of
1650 context @emph{properties}. Many of them can be changed to
1651 influence the interpretation of the input and so change the
1652 appearance of the output. They are changed by the
1653 @code{\set} command. This takes the form
1656 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1659 Where the @emph{ContextName} is usually @code{Score},
1660 @code{Staff} or @code{Voice}. It may be omitted,
1661 in which case the current context (typically @code{Voice}) is assumed.
1663 The names of context properties consist of words joined
1664 together with no hyphens or underscores, all except the
1665 first having a capital letter. Here are a few examples
1666 of some commonly used ones. There are many more.
1668 @c attempt to force this onto a new page
1670 @multitable @columnfractions .25 .15 .45 .15
1671 @headitem propertyName
1677 @tab If true, set extra natural signs before accidentals
1678 @tab @code{#t}, @code{#f}
1679 @item currentBarNumber
1681 @tab Set the current bar number
1685 @tab If true, print slurs both above and below notes
1686 @tab @code{#t}, @code{#f}
1687 @item instrumentName
1689 @tab Set the name to be placed at the start of the staff
1690 @tab @code{"Cello I"}
1693 @tab Increase or decrease the font size
1697 @tab Set the text to print before the start of a verse
1702 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1703 an Integer is a positive whole number, a Real is a positive
1704 or negative decimal number, and text is enclosed in double
1705 apostrophes. Note the occurrence of hash signs,
1706 (@code{#}), in two different places -- as part of the Boolean
1707 value before the @code{t} or @code{f}, and before @emph{value}
1708 in the @code{\set} statement. So when a Boolean is being
1709 entered you need to code two hash signs, e.g., @code{##t}.
1711 @cindex properties operating in contexts
1712 @cindex setting properties within contexts
1714 Before we can set any of these properties we need to know
1715 in which context they operate. Sometimes this is obvious,
1716 but occasionally it can be tricky. If the wrong context
1717 is specified, no error message is produced, but the expected
1718 action will not take place. For example, the
1719 @code{instrumentName} clearly lives in the @code{Staff} context, since
1720 it is the staff that is to be named.
1721 In this example the first staff is labeled, but not the second,
1722 because we omitted the context name.
1724 @lilypond[quote,verbatim,ragged-right]
1726 \new Staff \relative c'' {
1727 \set Staff.instrumentName = #"Soprano"
1730 \new Staff \relative c' {
1731 \set instrumentName = #"Alto" % Wrong!
1737 Remember the default context name is @code{Voice}, so the second
1738 @code{\set} command set the property @code{instrumentName} in the
1739 @code{Voice} context to @qq{Alto}, but as LilyPond does not look
1740 for any such property in the @code{Voice} context, no
1741 further action took place. This is not an error, and no error
1742 message is logged in the log file.
1744 Similarly, if the property name is mis-spelt no error message is
1745 produced, and clearly the expected action cannot be performed. In
1746 fact, you can set any (fictitious) @q{property} using any name you
1747 like in any context that exists by using the @code{\set} command. But
1748 if the name is not known to LilyPond it will not cause any action to
1749 be taken. Some text editors with special support for LilyPond input
1750 files document property names with bullets when you hover them with
1751 the mouse, like JEdit with LilyPondTool, or highlight unknown property
1752 names differently, like ConTEXT. If you do not use an editor with
1753 such features, it is recommended to check the property name in the
1754 Internals Reference: see @rinternals{Tunable context properties}, or
1755 @rinternals{Contexts}.
1757 The @code{instrumentName} property will take effect only
1758 if it is set in the @code{Staff} context, but
1759 some properties can be set in more than one context.
1760 For example, the property @code{extraNatural} is by
1761 default set to ##t (true) for all staves.
1762 If it is set to ##f (false) in one particular @code{Staff}
1763 context it applies just to the accidentals on that staff.
1764 If it is set to false in the @code{Score} context
1765 it applies to all staves.
1767 So this turns off extra naturals in one staff:
1769 @lilypond[quote,verbatim,ragged-right]
1771 \new Staff \relative c'' {
1774 \new Staff \relative c'' {
1775 \set Staff.extraNatural = ##f
1782 and this turns them off in all staves:
1784 @lilypond[quote,verbatim,ragged-right]
1786 \new Staff \relative c'' {
1789 \new Staff \relative c'' {
1790 \set Score.extraNatural = ##f
1796 As another example, if @code{clefOctavation} is set in
1797 the @code{Score} context this immediately changes the value
1798 of the octavation in all current staves and sets a new default
1799 value which will be applied to all staves.
1801 The opposite command, @code{\unset}, effectively removes the
1802 property from the context, which causes most properties to
1803 revert to their default value. Usually @code{\unset} is not
1804 required as a new @code{\set} command will achieve what is
1807 The @code{\set} and @code{\unset} commands can appear anywhere
1808 in the input file and will take effect from the time they are
1809 encountered until the end of the score or until the property is
1810 @code{\set} or @code{\unset} again. Let's try changing the
1811 font size, which affects the size of the note heads (among
1812 other things) several times. The change is from the default
1813 value, not the most recently set value.
1815 @lilypond[quote,verbatim,ragged-right,relative=1]
1817 % make note heads smaller
1820 % make note heads larger
1821 \set fontSize = #2.5
1823 % return to default size
1828 We have now seen how to set the values of several different types of
1829 property. Note that integers and numbers are always preceded by a
1830 hash sign, @code{#}, while a true or false value is specified by
1831 @code{##t} and @code{##f}, with two hash signs. A text property
1832 should be enclosed in double quotation signs, as above, although we
1833 shall see later that text can actually be specified in a much more
1834 general way by using the very powerful @code{\markup} command.
1836 @subsubheading Setting context properties with @code{\with}
1840 @cindex context properties, setting with \with
1842 The default value of context properties may be set at the time the
1843 context is created. Sometimes this is a clearer way of setting a
1844 property value if it is to remain fixed for the duration of
1845 the context. When a context is created with a @code{\new}
1846 command it may be followed immediately by a @code{\with @{ .. @}}
1847 block in which the default property values are set. For example,
1848 if we wish to suppress the printing of extra naturals for the
1849 duration of a staff we would write:
1852 \new Staff \with @{ extraNatural = ##f @}
1858 @lilypond[quote,verbatim,ragged-right]
1862 gisis4 gis aeses aes
1865 \new Staff \with { extraNatural = ##f } {
1867 gisis4 gis aeses aes
1873 Properties set in this way may still be changed dynamically using
1874 @code{\set} and returned to the default value set in the
1875 @code{\with} block with @code{\unset}.
1877 @cindex fontSize, default and setting
1879 So if the @code{fontSize} property is set in a @code{\with} clause
1880 it sets the default value of the font size. If it is later changed
1881 with @code{\set}, this new default value may be restored with the
1882 @code{\unset fontSize} command.
1884 @subsubheading Setting context properties with @code{\context}
1886 @cindex context properties, setting with \context
1890 The values of context properties may be set in @emph{all} contexts
1891 of a particular type, such as all @code{Staff} contexts, with a single
1892 command. The context type is identified by using its
1893 type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
1894 The statement which sets the property value is the same as that in a
1895 @code{\with} block, introduced above. It is placed in a
1896 @code{\context} block within a @code{\layout} block. Each
1897 @code{\context} block will affect all contexts of the type specified
1898 throughout the @code{\score} or @code{\book} block in which the
1899 @code{\layout} block appears. Here is a example to show the format:
1901 @lilypond[verbatim,quote]
1917 If the property override is to be applied to all staves
1920 @lilypond[quote,verbatim]
1925 gisis4 gis aeses aes
1930 gisis4 gis aeses aes
1936 \Score extraNatural = ##f
1943 Context properties set in this way may be overridden for particular
1944 instances of contexts by statements in a @code{\with} block, and by
1945 @code{\set} commands embedded in music statements.
1950 @ruser{Changing context default settings}.
1951 @ruser{The set command}.
1953 Internals Reference:
1954 @rinternals{Contexts},
1955 @rinternals{Tunable context properties}.
1958 @node Adding and removing engravers
1959 @subsection Adding and removing engravers
1961 @cindex engravers, adding
1962 @cindex adding engravers
1963 @cindex engravers, removing
1964 @cindex removing engravers
1971 We have seen that contexts each contain several engravers, each
1972 of which is responsible for producing a particular part of the
1973 output, like bar lines, staves, note heads, stems, etc. If an
1974 engraver is removed from a context, it can no longer produce its
1975 output. This is a crude way of modifying the output, but it
1976 can sometimes be useful.
1978 @subsubheading Changing a single context
1980 To remove an engraver from a single context we use the
1981 @code{\with} command placed immediately after the context creation
1982 command, as in the previous section.
1984 As an illustration, let's repeat an example from the previous section
1985 with the staff lines removed. Remember that the staff lines are
1986 produced by the @code{Staff_symbol_engraver}.
1988 @lilypond[quote,verbatim,ragged-right]
1990 \remove Staff_symbol_engraver
1994 \set fontSize = #-4 % make note heads smaller
1996 \set fontSize = #2.5 % make note heads larger
1998 \unset fontSize % return to default size
2003 @cindex ambitus engraver
2005 Engravers can also be added to individual contexts.
2006 The command to do this is
2008 @code{\consists @var{Engraver_name}},
2011 placed inside a @code{\with} block. Some vocal scores have an ambitus
2012 placed at the beginning of a staff to indicate the range of notes in
2013 that staff -- see @rglos{ambitus}. The ambitus is produced by the
2014 @code{Ambitus_engraver}, which is not normally included in any
2015 context. If we add it to the @code{Voice} context, it calculates the
2016 range from that voice only:
2018 @lilypond[quote,verbatim,ragged-right]
2021 \consists Ambitus_engraver
2038 but if we add the ambitus engraver to the
2039 @code{Staff} context, it calculates the range from all
2040 the notes in all the voices on that staff:
2042 @lilypond[quote,verbatim,ragged-right]
2044 \consists Ambitus_engraver
2062 @subsubheading Changing all contexts of the same type
2067 The examples above show how to remove or add engravers to
2068 individual contexts. It is also possible to remove or add
2069 engravers to every context of a specific type by placing the
2070 commands in the appropriate context in a @code{\layout}
2071 block. For example, if we wanted to show an ambitus for every
2072 staff in a four-staff score, we could write
2074 @lilypond[quote,verbatim,ragged-right]
2103 \consists Ambitus_engraver
2110 The values of context properties may also be set
2111 for all contexts of a particular type by including the
2112 @code{\set} command in a @code{\context} block in the
2116 Notation Reference: @ruser{Modifying context plug-ins},
2117 @ruser{Changing context default settings}.
2120 The @code{Stem_engraver} and @code{Beam_engraver} attach their
2121 objects to note heads. If the @code{Note_heads_engraver} is removed
2122 no note heads are produced and therefore no stems or beams are created
2126 @node Extending the templates
2127 @section Extending the templates
2129 You've read the tutorial, you know how to write music, you
2130 understand the fundamental concepts. But how can you
2131 get the staves that you want? Well, you can find lots of
2132 templates (see @ref{Templates}) which may give you a start.
2133 But what if you want something that isn't covered there? Read on.
2136 * Soprano and cello::
2137 * Four-part SATB vocal score::
2138 * Building a score from scratch::
2139 * Saving typing with variables and functions::
2140 * Scores and parts::
2143 @node Soprano and cello
2144 @subsection Soprano and cello
2146 @cindex template, modifying
2147 @cindex modifying templates
2149 Start off with the template that seems closest to what you want to
2150 end up with. Let's say that you want to write something for
2151 soprano and cello. In this case, we would start with the
2152 @q{Notes and lyrics} template (for the soprano part).
2155 \version @w{"@version{}"}
2157 melody = \relative c' @{
2164 text = \lyricmode @{
2170 \new Voice = "one" @{
2174 \new Lyrics \lyricsto "one" \text
2181 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2184 \version @w{"@version{}"}
2186 melody = \relative c' @{
2200 We don't need two @code{\version} commands. We'll need the
2201 @code{melody} section. We don't want two @code{\score} sections
2202 -- if we had two @code{\score}s, we'd get the two parts separately.
2203 We want them together, as a duet. Within the @code{\score}
2204 section, we don't need two @code{\layout} or @code{\midi}.
2206 If we simply cut and paste the @code{melody} section, we would
2207 end up with two @code{melody} definitions. This would not generate
2208 an error, but the second one would be used for both melodies.
2209 So let's rename them to make them distinct. We'll call the
2210 section for the soprano @code{sopranoMusic} and the section for
2211 the cello @code{celloMusic}. While we're doing this, let's rename
2212 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2213 instances of all these names -- both the initial definition (the
2214 @code{melody = \relative c' @{ } part) and the name's use (in the
2215 @code{\score} section).
2217 While we're doing this, let's change the cello part's staff --
2218 celli normally use bass clef. We'll also give the cello some
2222 \version @w{"@version{}"}
2224 sopranoMusic = \relative c' @{
2231 sopranoLyrics = \lyricmode @{
2235 celloMusic = \relative c @{
2244 \new Voice = "one" @{
2248 \new Lyrics \lyricsto "one" \sopranoLyrics
2255 This is looking promising, but the cello part won't appear in the
2256 score -- we haven't used it in the @code{\score} section. If we
2257 want the cello part to appear under the soprano part, we need to add
2260 \new Staff \celloMusic
2264 underneath the soprano stuff. We also need to add @code{<<} and
2265 @code{>>} around the music -- that tells LilyPond that there's
2266 more than one thing (in this case, two @code{Staves}) happening
2267 at once. The @code{\score} looks like this now:
2269 @c Indentation in this example is deliberately poor
2274 \new Voice = "one" @{
2278 \new Lyrics \lyricsto "one" \sopranoLyrics
2280 \new Staff \celloMusic
2288 This looks a bit messy; the indentation is messed up now. That is
2289 easily fixed. Here's the complete soprano and cello template.
2291 @lilypond[quote,verbatim,ragged-right,addversion]
2292 sopranoMusic = \relative c' {
2299 sopranoLyrics = \lyricmode {
2303 celloMusic = \relative c {
2313 \new Voice = "one" {
2317 \new Lyrics \lyricsto "one" \sopranoLyrics
2319 \new Staff \celloMusic
2328 The starting templates can be found in the @q{Templates} appendix,
2329 see @ref{Single staff}.
2332 @node Four-part SATB vocal score
2333 @subsection Four-part SATB vocal score
2335 @cindex template, SATB
2336 @cindex SATB template
2338 Most vocal scores of music written for four-part mixed choir
2339 with orchestral accompaniment such as Mendelssohn's Elijah or
2340 Handel's Messiah have the choral music and words on four
2341 staves, one for each of SATB, with a piano reduction of the
2342 orchestral accompaniment underneath. Here's an example
2343 from Handel's Messiah:
2345 @c The following should appear as music without code
2346 @lilypond[quote,ragged-right]
2347 global = { \key d \major \time 4/4 }
2349 sopranoMusic = \relative c'' {
2351 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2353 sopranoWords = \lyricmode {
2354 Wor -- thy | is the lamb | that was slain |
2357 altoMusic = \relative a' {
2359 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
2361 altoWords = \sopranoWords
2363 tenorMusic = \relative c' {
2365 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2367 tenorWords = \sopranoWords
2369 bassMusic = \relative c' {
2371 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2373 bassWords = \sopranoWords
2375 upper = \relative a' {
2378 r4 <a d fis>2 <a e' a>4 |
2379 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2380 <g cis g'>4 <a d fis> <a cis e>2 |
2383 lower = \relative c, {
2386 <d d'>4 <d d'>2 <cis cis'>4 |
2387 <b b'>4. <b' b'>8 <fis fis'>2 |
2388 <e e'>4 <d d'> <a' a'>2 |
2392 << % combine ChoirStaff and PianoStaff in parallel
2394 \new Staff = "sopranos" <<
2395 \set Staff.instrumentName = #"Soprano"
2396 \new Voice = "sopranos" {
2401 \new Lyrics \lyricsto "sopranos" {
2404 \new Staff = "altos" <<
2405 \set Staff.instrumentName = #"Alto"
2406 \new Voice = "altos" {
2411 \new Lyrics \lyricsto "altos" { \altoWords }
2412 \new Staff = "tenors" <<
2413 \set Staff.instrumentName = #"Tenor"
2414 \new Voice = "tenors" {
2419 \new Lyrics \lyricsto "tenors" { \tenorWords }
2420 \new Staff = "basses" <<
2421 \set Staff.instrumentName = #"Bass"
2422 \new Voice = "basses" {
2427 \new Lyrics \lyricsto "basses" {
2432 \set PianoStaff.instrumentName = #"Piano"
2433 \new Staff = "upper" \upper
2434 \new Staff = "lower" \lower
2440 None of the templates provides this layout exactly. The nearest is
2441 @q{SATB vocal score and automatic piano reduction} -- see
2442 @ref{Vocal ensembles} -- but we need to change the layout and add a piano
2443 accompaniment which is not derived automatically from the vocal parts.
2444 The variables holding the music and words for the vocal parts are
2445 fine, but we shall need to add variables for the piano reduction.
2447 The order in which the contexts appear in the ChoirStaff of the
2448 template do not correspond with the order in the vocal score shown
2449 above. We need to rearrange them so there are four staves with the
2450 words written directly underneath the notes for each part. All the
2451 voices should be @code{\voiceOne}, which is the default, so the
2452 @code{\voiceXXX} commands should be removed. We also need to specify
2453 the tenor clef for the tenors. The way in which lyrics are specified
2454 in the template has not yet been encountered so we need to use the
2455 method with which we are familiar. We should also add the names of
2458 Doing this gives for our ChoirStaff:
2462 \new Staff = "sopranos" <<
2463 \set Staff.instrumentName = #"Soprano"
2464 \new Voice = "sopranos" @{
2469 \new Lyrics \lyricsto "sopranos" @{
2472 \new Staff = "altos" <<
2473 \set Staff.instrumentName = #"Alto"
2474 \new Voice = "altos" @{
2479 \new Lyrics \lyricsto "altos" @{
2482 \new Staff = "tenors" <<
2483 \set Staff.instrumentName = #"Tenor"
2484 \new Voice = "tenors" @{
2489 \new Lyrics \lyricsto "tenors" @{
2492 \new Staff = "basses" <<
2493 \set Staff.instrumentName = #"Bass"
2494 \new Voice = "basses" @{
2499 \new Lyrics \lyricsto "basses" @{
2505 Next we must work out the piano part. This is
2506 easy - we just pull out the piano part from the
2507 @q{Solo piano} template:
2511 \set PianoStaff.instrumentName = #"Piano "
2512 \new Staff = "upper" \upper
2513 \new Staff = "lower" \lower
2517 and add the variable definitions for @code{upper}
2520 The ChoirStaff and PianoStaff must be combined
2521 using angle brackets as we want them to be
2522 stacked one above the other:
2525 << % combine ChoirStaff and PianoStaff one above the other
2527 \new Staff = "sopranos" <<
2528 \new Voice = "sopranos" @{
2533 \new Lyrics \lyricsto "sopranos" @{
2536 \new Staff = "altos" <<
2537 \new Voice = "altos" @{
2542 \new Lyrics \lyricsto "altos" @{
2545 \new Staff = "tenors" <<
2546 \clef "G_8" % tenor clef
2547 \new Voice = "tenors" @{
2552 \new Lyrics \lyricsto "tenors" @{
2555 \new Staff = "basses" <<
2557 \new Voice = "basses" @{
2562 \new Lyrics \lyricsto "basses" @{
2568 \set PianoStaff.instrumentName = #"Piano"
2569 \new Staff = "upper" \upper
2570 \new Staff = "lower" \lower
2575 Combining all these together and adding the music
2576 for the three bars of the example above gives:
2578 @lilypond[quote,verbatim,ragged-right,addversion]
2579 global = { \key d \major \time 4/4 }
2580 sopranoMusic = \relative c'' {
2582 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2584 sopranoWords = \lyricmode {
2585 Wor -- thy | is the lamb | that was slain |
2587 altoMusic = \relative a' {
2589 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2591 altoWords = \sopranoWords
2592 tenorMusic = \relative c' {
2594 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2596 tenorWords = \sopranoWords
2597 bassMusic = \relative c' {
2599 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2601 bassWords = \sopranoWords
2602 upper = \relative a' {
2605 r4 <a d fis>2 <a e' a>4 |
2606 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2607 <g cis g'>4 <a d fis> <a cis e>2 |
2609 lower = \relative c, {
2612 <d d'>4 <d d'>2 <cis cis'>4 |
2613 <b b'>4. <b' b'>8 <fis fis'>2 |
2614 <e e'>4 <d d'> <a' a'>2 |
2618 << % combine ChoirStaff and PianoStaff in parallel
2620 \new Staff = "sopranos" <<
2621 \set Staff.instrumentName = #"Soprano"
2622 \new Voice = "sopranos" {
2627 \new Lyrics \lyricsto "sopranos" {
2630 \new Staff = "altos" <<
2631 \set Staff.instrumentName = #"Alto"
2632 \new Voice = "altos" {
2637 \new Lyrics \lyricsto "altos" {
2640 \new Staff = "tenors" <<
2641 \set Staff.instrumentName = #"Tenor"
2642 \new Voice = "tenors" {
2647 \new Lyrics \lyricsto "tenors" {
2650 \new Staff = "basses" <<
2651 \set Staff.instrumentName = #"Bass"
2652 \new Voice = "basses" {
2657 \new Lyrics \lyricsto "basses" {
2663 \set PianoStaff.instrumentName = #"Piano "
2664 \new Staff = "upper" \upper
2665 \new Staff = "lower" \lower
2672 @node Building a score from scratch
2673 @subsection Building a score from scratch
2675 @cindex template, writing your own
2676 @cindex example of writing a score
2677 @cindex writing a score, example
2678 @cindex score, example of writing
2680 After gaining some facility with writing LilyPond code, you
2681 may find that it is easier to build a score from scratch
2682 rather than modifying one of the templates. You can also
2683 develop your own style this way to suit the sort of music you
2684 like. Let's see how to put together the score for an organ
2685 prelude as an example.
2687 We begin with a header section. Here go the title, name
2688 of composer, etc, then come any variable definitions, and
2689 finally the score block. Let's start with these in outline
2690 and fill in the details later.
2692 We'll use the first two bars of Bach's prelude
2693 based on @emph{Jesu, meine Freude} which is written for two
2694 manuals and pedal organ. You can see these two bars of music
2695 at the bottom of this section. The top manual part has two voices,
2696 the lower and pedal organ one each. So we need four
2697 music definitions and one to define the time signature
2701 \version @w{"@version{}"}
2703 title = "Jesu, meine Freude"
2704 composer = "J S Bach"
2706 keyTime = @{ \key c \minor \time 4/4 @}
2707 ManualOneVoiceOneMusic = @{ s1 @}
2708 ManualOneVoiceTwoMusic = @{ s1 @}
2709 ManualTwoMusic = @{ s1 @}
2710 PedalOrganMusic = @{ s1 @}
2716 For now we've just used a spacer note, @code{s1},
2717 instead of the real music. We'll add that later.
2719 Next let's see what should go in the score block.
2720 We simply mirror the staff structure we want.
2721 Organ music is usually written on three staves,
2722 one for each manual and one for the pedals. The
2723 manual staves should be bracketed together, so we
2724 need to use a PianoStaff for them. The first
2725 manual part needs two voices and the second manual
2730 \new Staff = "ManualOne" <<
2732 \ManualOneVoiceOneMusic
2735 \ManualOneVoiceTwoMusic
2737 >> % end ManualOne Staff context
2738 \new Staff = "ManualTwo" <<
2742 >> % end ManualTwo Staff context
2743 >> % end PianoStaff context
2746 Next we need to add a staff for the pedal organ.
2747 This goes underneath the PianoStaff, but it must
2748 be simultaneous with it, so we need angle brackets
2749 around the two. Missing these out would generate
2750 an error in the log file. It's a common mistake
2751 which you'll make sooner or later! Try copying
2752 the final example at the end of this section,
2753 remove these angle brackets, and compile it to
2754 see what errors it generates.
2757 << % PianoStaff and Pedal Staff must be simultaneous
2759 \new Staff = "ManualOne" <<
2761 \ManualOneVoiceOneMusic
2764 \ManualOneVoiceTwoMusic
2766 >> % end ManualOne Staff context
2767 \new Staff = "ManualTwo" <<
2771 >> % end ManualTwo Staff context
2772 >> % end PianoStaff context
2773 \new Staff = "PedalOrgan" <<
2781 It is not necessary to use the simultaneous construct
2782 @code{<< .. >>} for the manual two staff and the pedal organ staff,
2783 since they contain only one music expression, but it does no harm,
2784 and always using angle brackets after @code{\new Staff} is a good
2785 habit to cultivate in case there are multiple voices. The opposite
2786 is true for Voices: these should habitually be followed by braces
2787 @code{@{ .. @}} in case your music is coded in several variables
2788 which need to run consecutively.
2790 Let's add this structure to the score block, and adjust the indenting.
2791 We also add the appropriate clefs, ensure stems, ties and slurs in
2792 each voice on the upper staff point to the right direction with
2793 @code{\voiceOne} and @code{\voiceTwo}, and enter the key and time
2794 signature to each staff using our predefined variable, @code{\keyTime}.
2798 << % PianoStaff and Pedal Staff must be simultaneous
2800 \new Staff = "ManualOne" <<
2801 \keyTime % set key and time signature
2805 \ManualOneVoiceOneMusic
2809 \ManualOneVoiceTwoMusic
2811 >> % end ManualOne Staff context
2812 \new Staff = "ManualTwo" <<
2818 >> % end ManualTwo Staff context
2819 >> % end PianoStaff context
2820 \new Staff = "PedalOrgan" <<
2826 >> % end PedalOrgan Staff
2828 @} % end Score context
2831 @cindex stretchability of staves
2832 @cindex staves, stretchability
2834 The above layout of the organ staves is almost perfect; however,
2835 there is a slight defect which is not visible by looking at just a
2836 single system: The distance of the pedal staff to the left hand staff
2837 should behave approximately the same as the right hand staff to the
2838 left hand staff. In particular, the stretchability of staves in a
2839 @code{PianoStaff} context is limited (so that the distance between
2840 the staves for the left and right hand can't become too large), and
2841 the pedal staff should behave similarly.
2843 @cindex sub-properties
2844 @cindex properties, sub-properties
2845 @cindex graphical objects
2846 @cindex objects, graphical
2849 Stretchability of staves can be controlled with the
2850 @code{staff-staff-spacing} property of the
2851 @code{VerticalAxisGroup} @q{graphical object} (commonly called
2852 @q{grob}s within the lilypond documentation) -- don't worry about
2853 the details right now; this is fully explained later. For the
2854 curious, have a look at @ruser{Overview of modifying properties}.
2855 In this case, we want to modify the @code{stretchability}
2856 sub-property only. Again, for the curious, you can find the
2857 default values for the staff-staff-spacing property
2858 in file @file{scm/define-grobs.scm} by looking up the definition
2859 of the @code{VerticalAxisGroup} grob. The value for
2860 @code{stretchability} is taken from the definition of the
2861 @code{PianoStaff} context (in file @file{ly/engraver-init.ly})
2862 so that the values are identical.
2866 << % PianoStaff and Pedal Staff must be simultaneous
2868 \new Staff = "ManualOne" <<
2869 \keyTime % set key and time signature
2873 \ManualOneVoiceOneMusic
2877 \ManualOneVoiceTwoMusic
2879 >> % end ManualOne Staff context
2880 \new Staff = "ManualTwo" \with @{
2881 \override VerticalAxisGroup
2882 #'staff-staff-spacing #'stretchability = 5
2889 >> % end ManualTwo Staff context
2890 >> % end PianoStaff context
2891 \new Staff = "PedalOrgan" <<
2897 >> % end PedalOrgan Staff
2899 @} % end Score context
2901 That completes the structure. Any three-staff organ music
2902 will have a similar structure, although the number of voices
2903 may vary. All that remains now
2904 is to add the music, and combine all the parts together.
2906 @lilypond[quote,verbatim,ragged-right,addversion]
2908 title = "Jesu, meine Freude"
2909 composer = "J S Bach"
2911 keyTime = { \key c \minor \time 4/4 }
2912 ManualOneVoiceOneMusic = \relative g' {
2916 ManualOneVoiceTwoMusic = \relative c' {
2917 ees16 d ees8~ ees16 f ees d c8 d~ d c~ |
2918 c8 c4 b8 c8. g16 c b c d |
2920 ManualTwoMusic = \relative c' {
2921 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2922 f16 ees f d g aes g f ees d e8~ ees16 f ees d |
2924 PedalOrganMusic = \relative c {
2925 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2926 r16 g ees f g f g8 c,2 |
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
2946 #'staff-staff-spacing #'stretchability = 5
2953 >> % end ManualTwo Staff context
2954 >> % end PianoStaff context
2955 \new Staff = "PedalOrgan" <<
2961 >> % end PedalOrgan Staff context
2963 } % end Score context
2970 @node Saving typing with variables and functions
2971 @subsection Saving typing with variables and functions
2976 By this point, you've seen this kind of thing:
2978 @lilypond[quote,verbatim,ragged-right]
2979 hornNotes = \relative c'' { c4 b dis c }
2988 You may even realize that this could be useful in minimalist music:
2990 @lilypond[quote,verbatim,ragged-right]
2991 fragmentA = \relative c'' { a4 a8. b16 }
2992 fragmentB = \relative c'' { a8. gis16 ees4 }
2994 violin = \new Staff {
2995 \fragmentA \fragmentA |
2996 \fragmentB \fragmentA |
3006 However, you can also use these variables (also known as
3007 macros, or user-defined commands) for tweaks:
3009 @c TODO Avoid padtext - not needed with skylining
3010 @lilypond[quote,verbatim,ragged-right]
3011 dolce = \markup { \italic \bold dolce }
3013 padText = { \once \override TextScript #'padding = #5.0 }
3015 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
3018 violin = \relative c'' {
3020 c4._\dolce b8 a8 g a b |
3022 c4.^"hi there!" d8 e' f g d |
3023 c,4.\fthenp b8 c4 c-. |
3031 \layout { ragged-right = ##t }
3035 These variables are obviously useful for saving
3036 typing. But they're worth considering even if you
3037 only use them once -- they reduce complexity. Let's
3038 look at the previous example without any
3039 variables. It's a lot harder to read, especially
3043 violin = \relative c'' @{
3045 c4._\markup @{ \italic \bold dolce @} b8 a8 g a b |
3046 \once \override TextScript #'padding = #5.0
3047 c4.^"hi there!" d8 e' f g d |
3049 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p
3056 @c TODO Replace the following with a better example -td
3057 @c Skylining handles this correctly without padText
3059 So far we've seen static substitution -- when LilyPond
3060 sees @code{\padText}, it replaces it with the stuff that
3061 we've defined it to be (ie the stuff to the right of
3064 LilyPond can handle non-static substitution, too (you
3065 can think of these as functions).
3067 @lilypond[quote,verbatim,ragged-right]
3069 #(define-music-function
3070 (parser location padding)
3073 \once \override TextScript #'padding = $padding
3077 c4^"piu mosso" b a b |
3079 c4^"piu mosso" d e f |
3081 c4^"piu mosso" fis a g |
3085 Using variables is also a good way to reduce work if the
3086 LilyPond input syntax changes (see
3087 @rprogram{Updating files with convert-ly}). If
3088 you have a single definition (such as @code{\dolce}) for all your
3089 input files (see @ref{Style sheets}), then if the syntax changes, you
3090 only need to update your single @code{\dolce} definition,
3091 instead of making changes throughout every @file{.ly} file.
3094 @node Scores and parts
3095 @subsection Scores and parts
3097 In orchestral music, all notes are printed twice. Once in a part for
3098 the musicians, and once in a full score for the conductor. Variables can
3099 be used to avoid double work. The music is entered once, and stored in
3100 a variable. The contents of that variable is then used to generate
3101 both the part and the full score.
3103 It is convenient to define the notes in a special file. For example,
3104 suppose that the file @file{horn-music.ly} contains the following part
3105 of a horn/@/bassoon duo
3108 hornNotes = \relative c @{
3110 r4 f8 a | cis4 f | e4 d |
3115 Then, an individual part is made by putting the following in a file
3118 \include "horn-music.ly"
3121 instrument = "Horn in F"
3125 \transpose f c' \hornNotes
3132 \include "horn-music.ly"
3136 substitutes the contents of @file{horn-music.ly} at this position in
3137 the file, so @code{hornNotes} is defined afterwards. The command
3138 @code{\transpose f@tie{}c'} indicates that the argument, being
3139 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
3140 @code{f} is denoted by notated @code{c'}, which corresponds with the
3141 tuning of a normal French Horn in@tie{}F. The transposition can be seen
3142 in the following output
3144 @lilypond[quote,ragged-right]
3145 \transpose f c' \relative c {
3147 r4 f8 a | cis4 f | e4 d |
3151 In ensemble pieces, one of the voices often does not play for many
3152 measures. This is denoted by a special rest, the multi-measure
3153 rest. It is entered with a capital @code{R} followed by a duration
3154 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
3155 etc.). By multiplying the
3156 duration, longer rests can be constructed. For example, this rest
3157 takes 3@tie{}measures in 2/4 time
3163 When printing the part, multi-rests
3164 must be condensed. This is done by setting a run-time variable
3167 \set Score.skipBars = ##t
3171 This command sets the property @code{skipBars} in the
3172 @code{Score} context to true (@code{##t}). Prepending the rest and
3173 this option to the music above, leads to the following result
3175 @lilypond[quote,ragged-right]
3176 \transpose f c' \relative c {
3178 \set Score.skipBars = ##t
3180 r4 f8 a | cis4 f | e4 d |
3185 The score is made by combining all of the music together. Assuming
3186 that the other voice is in @code{bassoonNotes} in the file
3187 @file{bassoon-music.ly}, a score is made with
3190 \include "bassoon-music.ly"
3191 \include "horn-music.ly"
3194 \new Staff \hornNotes
3195 \new Staff \bassoonNotes
3202 @lilypond[quote,ragged-right]
3208 r4 f8 a | cis4 f | e4 d |
3213 r4 d,8 f | gis4 c | b4 bes |
3214 a8 e f4 | g4 d | gis4 f |