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{}"}
58 @var{...compound music expression...} % all the music goes here!
65 There are many variations of this basic pattern, but this
66 example serves as a useful starting place.
75 Up to this point none of the examples you have seen have used a
76 @code{\score@{@}} command. This is because LilyPond automatically
77 adds the extra commands which are needed when you give it simple
78 input. LilyPond treats input like this:
87 as shorthand for this:
104 In other words, if the input contains a single music expression,
105 LilyPond will interpret the file as though the music expression
106 was wrapped up inside the commands shown above.
108 @cindex implicit contexts
109 @cindex contexts, implicit
111 @strong{A word of warning!} Many of the examples in the LilyPond
112 documentation will omit the @code{\new Staff} and @code{\new Voice}
113 commands, leaving them to be created implicitly. For simple
114 examples this works well, but for more complex examples, especially
115 when additional commands are used, the implicit creation of contexts
116 can give surprising results, maybe creating extra unwanted staves.
117 The way to create contexts explicitly is explained in
118 @ref{Contexts and engravers}.
120 @warning{When entering more than a few lines of music it is
121 advisable to always create staves and voices explicitly.}
123 For now, though, let us return to the first example and examine the
124 @code{\score} command, leaving the others to default.
126 A @code{\score} block must always contain just one music expression,
127 and this must appear immediately after the @code{\score} command.
128 Remember that a music expression could be anything from a single
129 note to a huge compound expression like
134 @var{...insert the whole score of a Wagner opera in here...}
140 Since everything is inside @code{@{ ... @}}, it counts
141 as one music expression.
143 As we saw previously, the @code{\score} block can contain other
166 Note that these three commands -- @code{\header}, @code{\layout} and
167 @code{\midi} -- are special: unlike many other commands which begin
168 with a backward slash (@code{\}) they are @emph{not} music expressions
169 and are not part of any music expression. So they may be placed
170 inside a @code{\score} block or outside it. In fact, these commands
171 are commonly placed outside the @code{\score} block -- for example,
172 @code{\header} is often placed above the @code{\score} command, as the
173 example at the beginning of this section shows.
175 Two more commands you have not previously seen are
176 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
177 shown they will cause LilyPond to produce a printed output and a
178 MIDI output respectively. They are described fully in the
179 Notation Reference -- @ruser{Score layout}, and
180 @ruser{Creating MIDI files}.
182 @cindex scores, multiple
183 @cindex book block, implicit
184 @cindex implicit book block
188 You may code multiple @code{\score} blocks. Each will be
189 treated as a separate score, but they will be all combined into
190 a single output file. A @code{\book} command is not necessary
191 -- one will be implicitly created. However, if you would like
192 separate output files from one @code{.ly} file then the
193 @code{\book} command should be used to separate the different
194 sections: each @code{\book} block will produce a
195 separate output file.
199 Every @code{\book} block creates a separate output file (e.g., a
200 PDF file). If you haven't explicitly added one, LilyPond wraps
201 your entire input code in a @code{\book} block implicitly.
203 Every @code{\score} block is a separate chunk of music within a
206 @cindex layout block, effect of location
208 Every @code{\layout} block affects the @code{\score} or
209 @code{\book} block in which it appears -- i.e., a @code{\layout}
210 block inside a @code{\score} block affects only that @code{\score}
211 block, but a @code{\layout} block outside of a @code{\score} block
212 (and thus in a @code{\book} block, either explicitly or
213 implicitly) will affect every @code{\score} in that @code{\book}.
215 For details see @ruser{Multiple scores in a book}.
219 Another great shorthand is the ability to define variables (see
220 @ref{Organizing pieces with variables}. All the templates use this
223 melody = \relative c' @{
232 When LilyPond looks at this file, it takes the value of
233 @code{melody} (everything after the equals sign) and inserts it
234 whenever it sees @code{\melody}. There's nothing special about
235 the names -- it could be @code{melody}, @code{global},
237 @code{pianorighthand}, or @code{foofoobarbaz}. For more details,
238 see @ref{Saving typing with variables and functions}.
239 Remember that you can use almost any name you like as long
240 as it contains just alphabetic characters and is distinct from
241 LilyPond command names. The exact
242 limitations on variable names are detailed in
243 @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 begin with a compound music expression.}
275 To understand what is meant by a music expression and a compound
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{<< ... >>} instead of @code{@{ ... @}} 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{<< ... >>}
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{<< ... >>} 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 e2 }
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{@{ .. @}}
487 @tab Encloses a sequential segment of music
489 @tab Encloses the notes of a chord
490 @item @code{<< .. >>}
491 @tab Encloses simultaneous music expressions
493 @tab Marks the start and end of a slur
494 @item @code{\( .. \)}
495 @tab Marks the start and end of a phrasing slur
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{\times x/y @{..@}}, and grace notes
503 written as @code{\grace@{..@}}.
505 Outside LilyPond, the conventional use of brackets requires the
506 different types to be properly nested, like this, @code{<< [ @{ ( .. )
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,fragment,ragged-right,relative=2]
523 { g8\( a b[ c b\) a] }
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,fragment,ragged-right]
535 r16[ g16 \times 2/3 {r16 e'8] }
536 g16( a \times 2/3 {b d) e' }
537 g8[( a \times 2/3 {b d') e'~]}
538 \times 4/5 {e'32\( a b d' e'} a'4.\)
543 @node Voices contain music
544 @section Voices contain music
546 Singers need voices to sing, and so does LilyPond.
547 The actual music for all instruments in a score
548 is contained in Voices -- the most fundamental
549 of all LilyPond's concepts.
552 * I'm hearing Voices::
553 * Explicitly instantiating voices::
554 * Voices and vocals::
557 @node I'm hearing Voices
558 @subsection I'm hearing Voices
562 @cindex multiple voices
563 @cindex voices, multiple
564 @cindex Voice context
565 @cindex context, Voice
566 @cindex simultaneous music
567 @cindex music, simultaneous
568 @cindex concurrent music
569 @cindex music, concurrent
570 @cindex voices vs. chords
571 @cindex chords vs. voices
573 The lowest, most fundamental or innermost layers in a LilyPond
574 score are called @q{Voice contexts} or just @q{Voices} for short.
575 Voices are sometimes called @q{layers} in other notation
578 In fact, a Voice layer or context is the only one which can contain
579 music. If a Voice context is not explicitly declared one is created
580 automatically, as we saw at the beginning of this chapter. Some
581 instruments such as an Oboe can play only one note at a time. Music
582 written for such instruments is monophonic and requires just a single
583 voice. Instruments which can play more than one note at a time like
584 the piano will often require multiple voices to encode the different
585 concurrent notes and rhythms they are capable of playing.
587 A single voice can contain many notes in a chord, of course,
588 so when exactly are multiple voices needed? Look first at
589 this example of four chords:
591 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
593 <d g>4 <d fis> <d a'> <d g>
596 This can be expressed using just the single angle bracket chord
597 symbols, @code{< ... >}, and for this just a single voice is
598 needed. But suppose the F-sharp were actually an eighth-note
599 followed by an eighth-note G, a passing note on the way to the A?
600 Now we have two notes which start at the same time but have
601 different durations: the quarter-note D and the eighth-note
602 F-sharp. How are these to be coded? They cannot be written as
603 a chord because all the notes in a chord must have the same
604 duration. And they cannot be written as two sequential notes
605 as they need to start at the same time. This is when two
608 Let us see how this is done in LilyPond input syntax.
613 The easiest way to enter fragments with more than one voice on a
614 staff is to enter each voice as a sequence (with @code{@{...@}}),
615 and combine them simultaneously with angle brackets, @code{<<...>>}.
616 The fragments must also be separated with double backward slashes,
617 @code{\\}, to place them in separate voices. Without these, the
618 notes would be entered into a single voice, which would usually
619 cause errors. This technique is particularly suited to pieces of
620 music which are largely monophonic with occasional short sections
623 Here's how we split the chords above into two voices and add both
624 the passing note and a slur:
626 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
628 % Voice "1" Voice "2"
629 << { g4 fis8( g) a4 g } \\ { d4 d d d } >> |
632 Notice how the stems of the second voice now point down.
634 Here's another simple example:
636 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
638 % Voice "1" Voice "2"
639 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
640 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
641 << { a2. r4 } \\ { fis2. s4 } >> |
644 It is not necessary to use a separate @code{<< \\ >>} construct
645 for each bar. For music with few notes in each bar this layout
646 can help the legibility of the code, but if there are many
647 notes in each bar it may be better to split out each voice
648 separately, like this:
650 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
666 @cindex voices, naming
667 @cindex voices crossing brackets
668 @cindex slurs crossing brackets
669 @cindex ties crossing brackest
671 This example has just two voices, but the same construct may be
672 used to encode three or more voices by adding more back-slash
675 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
676 In each of these contexts, the vertical direction of slurs,
677 stems, ties, dynamics etc., is set appropriately.
679 @lilypond[quote,verbatim,fragment]
680 \new Staff \relative c' {
683 % Voice "1" Voice "2" Voice "3"
684 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
685 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
689 These voices are all separate from the main voice that contains
690 the notes just outside the @code{<< .. >>} construct. Let's call
691 this the @emph{simultaneous construct}. Slurs and ties may only
692 connect notes within the same voice, so slurs and ties cannot go
693 into or out of a simultaneous construct. Conversely,
694 parallel voices from separate simultaneous constructs on the same
695 staff are the same voice. Other voice-related properties also
696 carry across simultaneous constructs. Here is the same example,
697 with different colors and note heads for each voice. Note that
698 changes in one voice do not affect other voices, but they do
699 persist in the same voice later. Note also that tied notes may be
700 split across the same voices in two constructs, shown here in the
703 @lilypond[quote,verbatim]
704 \new Staff \relative c' {
723 { c8 b16 a b8 g ~ g2 }
733 @funindex \voiceOneStyle
734 @funindex \voiceTwoStyle
735 @funindex \voiceThreeStyle
736 @funindex \voiceFourStyle
737 @funindex \voiceNeutralStyle
739 The commands @code{\voiceXXXStyle} are mainly intended for use in
740 educational documents such as this one. They modify the color
741 of the note head, the stem and the beams, and the style of the
742 note head, so that the voices may be easily distinguished.
743 Voice one is set to red diamonds, voice two to blue triangles,
744 voice three to green crossed circles, and voice four (not used
745 here) to magenta crosses; @code{\voiceNeutralStyle} (also not
746 used here) reverts the style back to the default.
747 We shall see later how commands like these may be created by the
749 See @ref{Visibility and color of objects} and
750 @ref{Using variables for tweaks}.
752 @cindex polyphony and relative note entry
753 @cindex relative note entry and polyphony
755 Polyphony does not change the relationship of notes within a
756 @code{\relative @{ @}} block. Each note is still calculated
757 relative to the note immediately preceding it, or to the first
758 note of the preceding chord. So in
761 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
765 @code{noteB} is relative to @code{noteA} @*
766 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
767 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
769 @code{noteE} is relative to @code{noteD}, not @code{noteA}.
771 An alternative way, which may be clearer if the notes in the
772 voices are widely separated, is to place a @code{\relative}
773 command at the start of each voice:
776 \relative c' @{ noteA ... @}
778 \relative c'' @{ < noteB noteC > ... @}
780 \relative g' @{ noteD ... @}
782 \relative c' @{ noteE ... @}
785 Let us finally analyze the voices in a more complex piece of music.
786 Here are the notes from the first two bars of the second of Chopin's
787 Deux Nocturnes, Op 32. This example will be used at later stages in
788 this and the next chapter to illustrate several techniques for
789 producing notation, so please ignore for now anything in the
790 underlying code which looks mysterious and concentrate just on the
791 music and the voices -- the complications will all be explained in
794 @c The following should appear as music without code
795 @lilypond[quote,ragged-right]
796 \new Staff \relative c'' {
805 % Ignore these for now - they are explained in Ch 4
806 \once \override NoteColumn #'force-hshift = #0
808 \once \override NoteColumn #'force-hshift = #0.5
816 The direction of the stems is often used to indicate the continuity of
817 two simultaneous melodic lines. Here the stems of the highest notes
818 are all pointing up and the stems of the lower notes are all pointing
819 down. This is the first indication that more than one voice is
822 But the real need for multiple voices arises when notes
823 which start at the same time have different durations.
824 Look at the notes which start at beat three in the first
825 bar. The A-flat is a dotted quarter note, the F is a
826 quarter note and the D-flat is a half note. These
827 cannot be written as a chord as all the notes in a chord
828 must have the same duration. Neither can they be written
829 as sequential notes, as they must start at the same time.
830 This section of the bar requires three voices, and the
831 normal practice would be to write the whole bar as three
832 voices, as shown below, where we have used different note heads
833 and colors for the three voices. Again, the code behind this
834 example will be explained later, so ignore anything you do
837 @c The following should appear as music without code
838 @c The three voice styles should be defined in -init
839 @lilypond[quote,ragged-right]
840 \new Staff \relative c'' {
851 \\ % No Voice three (we want stems down)
854 % Ignore these for now - they are explained in Ch 4
855 \once \override NoteColumn #'force-hshift = #0
857 \once \override NoteColumn #'force-hshift = #0.5
866 Let us try to encode this music from scratch. As we
867 shall see, this encounters some difficulties. We begin as
868 we have learnt, using the @code{<< \\ >>} construct to
869 enter the music of the first bar in three voices:
871 @lilypond[quote,verbatim,fragment,ragged-right]
872 \new Staff \relative c'' {
875 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
882 @cindex voices and stem directions
883 @cindex stem directions and voices
886 The stem directions are automatically assigned with the
887 odd-numbered voices taking upward stems and the even-numbered
888 voices downward ones. The stems for voices 1 and 2 are right,
889 but the stems in voice 3 should go down in this particular piece
890 of music. We can correct this by skipping voice three
891 and placing the music in voice four. This is done by simply
892 adding another pair of @code{\\}.
894 @lilypond[quote,verbatim,fragment,ragged-right]
895 \new Staff \relative c'' {
901 \\ % Omit Voice three
910 We see that this fixes the stem direction, but exposes a problem
911 sometimes encountered with multiple voices -- the stems of the notes
912 in one voice can collide with the note heads in other voices. In
913 laying out the notes, LilyPond allows the notes or chords from two
914 voices to occupy the same vertical note column provided the stems are
915 in opposite directions, but the notes from the third and fourth voices
916 are displaced, if necessary, to avoid the note heads colliding. This
917 usually works well, but in this example the notes of the lowest voice
918 are clearly not well placed by default. LilyPond provides several ways
919 to adjust the horizontal placing of notes. We are not quite ready yet
920 to see how to correct this, so we shall leave this problem until a
921 later section --- see the @code{force-hshift} property in @ref{Fixing
922 overlapping notation}.
926 Notation Reference: @ruser{Multiple voices}.
929 @node Explicitly instantiating voices
930 @subsection Explicitly instantiating voices
936 @funindex \voiceThree
943 @cindex voice contexts, creating
945 Voice contexts can also be created manually
946 inside a @code{<< >>} block to create polyphonic music, using
947 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
948 directions of stems, slurs, etc. In longer scores this method
949 is clearer, as it permits the voices to be separated and to be
950 given more descriptive names.
952 Specifically, the construct @code{<< \\ >>} which we used in
953 the previous section:
958 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
968 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
969 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
973 Both of the above would produce
975 @c The following example should not display the code
976 @lilypond[ragged-right,quote]
978 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
979 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
983 @cindex voices, reverting to single
984 @cindex reverting to a single voice
986 The @code{\voiceXXX} commands set the direction of stems, slurs,
987 ties, articulations, text annotations, augmentation dots of dotted
988 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
989 make these objects point upwards, while @code{\voiceTwo} and
990 @code{\voiceFour} make them point downwards. These commands also
991 generate a horizontal shift for each voice when this is required
992 to avoid clashes of note heads. The command @code{\oneVoice}
993 reverts the settings back to the normal values for a single voice.
995 Let us see in some simple examples exactly what effect
996 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
997 markup, ties, slurs, and dynamics:
999 @lilypond[quote,ragged-right,verbatim]
1001 % Default behavior or behavior after \oneVoice
1002 c d8 ~ d e4 ( f g a ) b-> c
1006 @lilypond[quote,ragged-right,verbatim]
1009 c d8 ~ d e4 ( f g a ) b-> c
1011 c, d8 ~ d e4 ( f g a ) b-> c
1015 @lilypond[quote,ragged-right,verbatim]
1018 c d8 ~ d e4 ( f g a ) b-> c
1020 c, d8 ~ d e4 ( f g a ) b-> c
1024 Now let's look at three different ways to notate the same passage
1025 of polyphonic music, each of which is advantageous in different
1026 circumstances, using the example from the previous section.
1028 An expression that appears directly inside a @code{<< >>} belongs
1029 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
1030 construct). This is useful when extra voices appear while the
1031 main voice is playing. Here is a more correct rendition of our
1032 example. The red diamond-shaped notes
1033 demonstrate that the main melody is now in a single voice context,
1034 permitting a phrasing slur to be drawn over them.
1036 @lilypond[quote,ragged-right,verbatim]
1037 \new Staff \relative c' {
1039 % The following notes are monophonic
1041 % Start simultaneous section of three voices
1043 % Continue the main voice in parallel
1045 % Initiate second voice
1047 % Set stems, etc, down
1049 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
1051 % Initiate third voice
1053 % Set stems, etc, up
1061 @cindex nesting music expressions
1062 @cindex nesting simultaneous constructs
1063 @cindex nesting voices
1064 @cindex voices, temporary
1065 @cindex voices, nesting
1067 More deeply nested polyphony constructs are possible, and if a
1068 voice appears only briefly this might be a more natural way to
1071 @lilypond[quote,ragged-right,verbatim]
1072 \new Staff \relative c' {
1080 {c8 b16 a b8 g ~ g2}
1091 @cindex spacing notes
1093 This method of nesting new voices briefly is useful
1094 when only small sections of the music
1095 are polyphonic, but when the whole staff is largely polyphonic
1096 it can be clearer to use multiple voices throughout, using
1097 spacing notes to step over sections where the voice is silent,
1100 @lilypond[quote,ragged-right,verbatim]
1101 \new Staff \relative c' <<
1102 % Initiate first voice
1105 c16^( d e f g4 f e | d2 e2) |
1107 % Initiate second voice
1109 % Set stems, etc, down
1111 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
1113 % Initiate third voice
1115 % Set stems, etc, up
1122 @subsubheading Note columns
1125 @cindex note collisions
1126 @cindex collisions, notes
1127 @cindex shift commands
1134 @funindex \shiftOnnn
1137 Closely spaced notes in a chord, or notes occurring at the same
1138 time in different voices, are arranged in two, occasionally more,
1139 columns to prevent the note heads overlapping. These are called
1140 note columns. There are separate columns for each voice, and
1141 the currently specified voice-dependent shift is applied to the
1142 note column if there would otherwise be a collision. This can
1143 be seen in the example above. In bar 2 the C in voice two is
1144 shifted to the right relative to the D in voice one, and in the
1145 final chord the C in voice three is also shifted to the right
1146 relative to the other notes.
1148 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1149 @code{\shiftOff} commands specify the degree to which notes and
1150 chords of the voice should be shifted if a collision
1151 would otherwise occur. By default, the outer voices (normally
1152 voices one and two) have @code{\shiftOff} specified, while the
1153 inner voices (three and four) have @code{\shiftOn} specified.
1154 When a shift is applied, voices one and three are shifted to
1155 the right and voices two and four to the left.
1157 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1158 levels which may be specified temporarily to resolve collisions
1159 in complex situations -- see @ref{Real music example}.
1161 A note column can contain just one note (or chord) from a voice
1162 with stems up and one note (or chord) from a voice with stems
1163 down. If notes from two voices which have their stems in the
1164 same direction are placed at the same position and both voices
1165 have no shift or the same shift specified, the error message
1166 @qq{Too many clashing note columns} will be produced.
1170 Notation Reference: @ruser{Multiple voices}.
1173 @node Voices and vocals
1174 @subsection Voices and vocals
1176 Vocal music presents a special difficulty: we need to combine two
1177 expressions -- notes and lyrics.
1179 @funindex \new Lyrics
1183 @cindex Lyrics context, creating
1184 @cindex lyrics, linking to voice
1186 You have already seen the @code{\addlyrics@{@}} command, which
1187 handles simple scores well. However, this technique is
1188 quite limited. For more complex music, you must introduce the
1189 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1191 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1192 name assigned to the Voice.
1194 @lilypond[quote,verbatim,fragment]
1196 \new Voice = "one" \relative c'' {
1199 c4 b8. a16 g4. f8 e4 d c2
1201 \new Lyrics \lyricsto "one" {
1202 No more let sins and sor -- rows grow.
1207 Note that the lyrics must be linked to a @code{Voice} context,
1208 @emph{not} a @code{Staff} context. This is a case where it is
1209 necessary to create @code{Staff} and @code{Voice} contexts
1212 @cindex lyrics and beaming
1213 @cindex beaming and lyrics
1214 @funindex \autoBeamOff
1215 @funindex autoBeamOff
1217 The automatic beaming which LilyPond uses by default works well
1218 for instrumental music, but not so well for music with lyrics,
1219 where beaming is either not required at all or is used to indicate
1220 melismata in the lyrics. In the example above we use the command
1221 @code{\autoBeamOff} to turn off the automatic beaming.
1223 @funindex \new ChoirStaff
1224 @funindex ChoirStaff
1225 @funindex \lyricmode
1227 @cindex vocal score structure
1230 Let us reuse the earlier example from Judas Maccabæus to
1231 illustrate this more flexible technique. We first recast
1232 it to use variables so the music and lyrics can be separated
1233 from the staff structure. We also introduce a ChoirStaff
1234 bracket. The lyrics themselves must be introduced with
1235 @code{\lyricmode} to ensure they are interpreted as lyrics
1238 @lilypond[quote,verbatim]
1239 global = { \time 6/8 \partial 8 \key f \major}
1240 SopOneMusic = \relative c'' {
1241 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
1242 SopTwoMusic = \relative c' {
1243 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
1244 SopOneLyrics = \lyricmode {
1245 Let | flee -- cy flocks the | hills a -- dorn, __ }
1246 SopTwoLyrics = \lyricmode {
1247 Let | flee -- cy flocks the | hills a -- dorn, }
1252 \new Voice = "SopOne" {
1256 \new Lyrics \lyricsto "SopOne" {
1261 \new Voice = "SopTwo" {
1265 \new Lyrics \lyricsto "SopTwo" {
1273 This is the basic structure of all vocal scores. More staves may be
1274 added as required, more voices may be added to the staves, more verses
1275 may be added to the lyrics, and the variables containing the music can
1276 easily be placed in separate files should they become too long.
1278 @cindex hymn structure
1279 @cindex SATB structure
1280 @cindex vocal scores with multiple verses
1281 @cindex multiple vocal verses
1282 @cindex verses, multiple vocal
1284 Here is an example of the first line of a hymn with four
1285 verses, set for SATB. In this case the words for all four
1286 parts are the same. Note how we use variables to separate the
1287 music notation and words from the staff structure. See too
1288 how a variable, which we have chosen to call @q{TimeKey}, is used
1289 to hold several commands for use within the two staves. In other
1290 examples this is often called @q{global}.
1292 @lilypond[quote,verbatim]
1293 TimeKey = { \time 4/4 \partial 4 \key c \major}
1294 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
1295 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
1296 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1297 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1298 VerseOne = \lyricmode {
1299 E -- | ter -- nal fa -- ther, | strong to save, }
1300 VerseTwo = \lyricmode {
1301 O | Christ, whose voice the | wa -- ters heard, }
1302 VerseThree = \lyricmode {
1303 O | Ho -- ly Spi -- rit, | who didst brood }
1304 VerseFour = \lyricmode {
1305 O | Tri -- ni -- ty of | love and pow'r }
1311 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1312 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1313 \new Lyrics \lyricsto "Sop" { \VerseOne }
1314 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1315 \new Lyrics \lyricsto "Sop" { \VerseThree }
1316 \new Lyrics \lyricsto "Sop" { \VerseFour }
1320 \new Voice = "Tenor" { \voiceOne \TimeKey \TenorMusic }
1321 \new Voice = "Bass" { \voiceTwo \BassMusic }
1327 @cindex verse and refrain
1329 We end with an example to show how we might code a solo verse which
1330 continues into a two-part refrain in two staves. The
1331 positioning of the sequential and simultaneous sections to achieve
1332 this within a single score is quite tricky, so follow the
1333 explanation carefully!
1335 Let's start with a score block containing a @code{ChoirStaff}, as
1336 we would like the brace to appear at the start of the chorus.
1337 Normally you would need angle brackets after @code{\new ChoirStaff}
1338 to bring in all the staves in parallel, but here we want to
1339 defer the parallelism during the solo so we use braces, although
1340 angle brackets here wouldn't hurt. Inside the @code{ChoirStaff} we
1341 want first the staff which will contain the verse. This must
1342 contain notes and lyrics in parallel, so here we need angle
1343 brackets around the @code{\new Voice} and @code{\new Lyrics} to
1344 start them at the same time:
1346 @lilypond[quote,verbatim,ragged-right]
1347 versenotes = \relative c'' {
1350 \time 3/4 g g g b b b
1352 versewords = \lyricmode {
1353 One two three four five six
1358 \new Voice = "verse" {
1361 \new Lyrics \lyricsto verse {
1369 That gives the verse line.
1371 Now we want to continue with refrainA on the same staff while a
1372 second staff is introduced in parallel with it for refrainB, so
1373 this is a parallel section which must be positioned immediately
1374 following the @code{\break} in the verse Voice. Yes, @emph{within}
1375 the verse Voice! Here's that parallel section. More staves
1376 could be introduced here in the same way.
1381 \new Lyrics \lyricsto verse @{
1385 \new Voice = "refrainB" @{
1388 \new Lyrics \lyricsto "refrainB" @{
1395 Here's the final result with two staves in the chorus showing
1396 how the parallel section is positioned within the verse Voice:
1398 @lilypond[quote,verbatim, ragged-right]
1399 versenotes = \relative c'' {
1402 \time 3/4 g g g b b b
1404 refrainnotesA = \relative c'' {
1408 refrainnotesB = \relative c {
1413 versewords = \lyricmode {
1414 One two three four five six
1416 refrainwordsA = \lyricmode {
1419 refrainwordsB = \lyricmode {
1425 \new Voice = "verse" {
1429 \new Lyrics \lyricsto "verse" {
1433 \new Voice = "refrainB" {
1436 \new Lyrics \lyricsto "refrainB" {
1442 \new Lyrics \lyricsto "verse" {
1450 @cindex book, example of using
1454 However, although this is an interesting and useful exercise to
1455 help you to understand how sequential and simultaneous blocks work,
1456 in practice one would perhaps choose to code this as two
1457 @code{\score} blocks within an implicit @code{\book} block, as
1460 @lilypond[quote,verbatim,ragged-right]
1461 versenotes = \relative c'' {
1464 \time 3/4 g g g b b b
1466 refrainnotesA = \relative c'' {
1470 refrainnotesB = \relative c {
1475 versewords = \lyricmode {
1476 One two three four five six
1478 refrainwordsA = \lyricmode {
1481 refrainwordsB = \lyricmode {
1486 \new Voice = "verse" {
1489 \new Lyrics \lyricsto "verse" {
1498 \new Voice = "refrainA" {
1501 \new Lyrics \lyricsto "refrainA" {
1506 \new Voice = "refrainB" {
1509 \new Lyrics \lyricsto "refrainB" {
1519 Notation Reference: @ruser{Vocal music}.
1522 @node Contexts and engravers
1523 @section Contexts and engravers
1525 Contexts and engravers have been mentioned informally
1526 in earlier sections; we now must look at
1527 these concepts in more detail, as they are important
1528 in the fine-tuning of LilyPond output.
1532 * Contexts explained::
1533 * Creating contexts::
1534 * Engravers explained::
1535 * Modifying context properties::
1536 * Adding and removing engravers::
1539 @node Contexts explained
1540 @subsection Contexts explained
1542 @cindex contexts explained
1544 When music is printed, many notational elements which do not
1545 appear explicitly in the input file must be added to the
1546 output. For example, compare the input and output of the
1549 @lilypond[quote,verbatim,relative=2,fragment]
1553 The input is rather sparse, but in the output, bar lines,
1554 accidentals, clef, and time signature have been added. When
1555 LilyPond @emph{interprets} the input the musical information
1556 is parsed from left to right, similar to the way a performer
1557 reads the score. While reading the input, the program remembers
1558 where measure boundaries are, and which pitches require explicit
1559 accidentals. This information must be held on several levels.
1560 For example, an accidental affects only a single staff, while
1561 a bar line must be synchronized across the entire score.
1563 Within LilyPond, these rules and bits of information are grouped in
1564 @emph{Contexts}. We have already introduced the @code{Voice} context.
1565 Others are the @code{Staff} and @code{Score} contexts. Contexts are
1566 hierarchical to reflect the hierarchical nature of a musical score.
1567 For example: a @code{Staff} context can contain many @code{Voice}
1568 contexts, and a @code{Score} context can contain many @code{Staff}
1572 @sourceimage{context-example,5cm,,}
1575 Each context has the responsibility for enforcing some notation rules,
1576 creating some notation objects and maintaining the associated
1577 properties. For example, the @code{Voice} context may introduce an
1578 accidental and then the @code{Staff} context maintains the rule to
1579 show or suppress the accidental for the remainder of the measure.
1581 As another example, the synchronization of bar lines is, by default,
1582 handled in the @code{Score} context.
1583 However, in some music we may not want the bar lines to be
1584 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1585 In such cases, we must modify the default settings of the
1586 @code{Score} and @code{Staff} contexts.
1588 For very simple scores, contexts are created implicitly, and you need
1589 not be aware of them. For larger pieces, such as anything with more
1590 than one staff, they must be
1591 created explicitly to make sure that you get as many staves as you
1592 need, and that they are in the correct order. For typesetting pieces
1593 with specialized notation, it is usual to modify existing, or
1594 even to define totally new, contexts.
1596 In addition to the @code{Score,} @code{Staff} and
1597 @code{Voice} contexts there are contexts which fit between
1598 the score and staff levels to control staff groups, such as the
1599 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1600 are also alternative staff and voice contexts, and contexts for
1601 lyrics, percussion, fret boards, figured bass, etc.
1603 The names of all context types are formed from one or more
1604 words, each word being capitalized and joined immediately to the
1605 preceding word with no hyphen or underscore, e.g.,
1606 @code{GregorianTranscriptionStaff}.
1610 Notation Reference: @ruser{Contexts explained}.
1613 @node Creating contexts
1614 @subsection Creating contexts
1618 @cindex new contexts
1619 @cindex creating contexts
1620 @cindex contexts, creating
1622 In an input file a score block, introduced with a @code{\score}
1623 command, contains a single music expression and an associated
1624 output definition (either a @code{\layout} or a @code{\midi} block).
1625 The @code{Score} context is usually left to be created automatically
1626 when the interpretation of that music expression starts.
1628 For scores with only one voice and one staff, the @code{Voice} and
1629 @code{Staff} contexts may also be left to be created automatically,
1630 but for more complex scores it is necessary to create them by hand.
1631 The simplest command that does this is @code{\new}. It is prepended
1632 to a music expression, for example
1635 \new @var{type} @var{music-expression}
1639 where @var{type} is a context name (like @code{Staff} or
1640 @code{Voice}). This command creates a new context, and starts
1641 interpreting the @var{music-expression} within that context.
1643 (Note that a @code{\new Score} command is not normally required,
1644 as the essential top-level @code{Score} context is created
1645 automatically when the music expression within the @code{\score}
1646 block is interpreted. The only reason for creating a @code{Score}
1647 context explicitly using @code{\new Score} is to introduce a
1648 @code{\with} block in which one or more score-wide default values
1649 of context properties may be specified. Information on using
1650 @code{\with} blocks can be found under the heading
1651 @qq{Setting context properties with @code{\\with} } in
1652 @ref{Modifying context properties}.)
1654 You have seen many practical examples which created new
1655 @code{Staff} and @code{Voice} contexts in earlier sections, but
1656 to remind you how these commands are used in practice, here's an
1657 annotated real-music example:
1659 @lilypond[quote,verbatim,ragged-right]
1660 \score { % start of single compound music expression
1661 << % start of simultaneous staves section
1663 \new Staff { % create RH staff
1666 \new Voice { % create voice for RH notes
1667 \relative c'' { % start of RH notes
1673 \new Staff << % create LH staff; needs two simultaneous voices
1676 \new Voice { % create LH voice one
1678 \relative g { % start of LH voice one notes
1679 g8 <bes d> ees, <g c> |
1680 g8 <bes d> ees, <g c> |
1681 } % end of LH voice one notes
1682 } % end of LH voice one
1683 \new Voice { % create LH voice two
1685 \relative g { % start of LH voice two notes
1688 } % end of LH voice two notes
1689 } % end of LH voice two
1690 >> % end of LH staff
1691 >> % end of simultaneous staves section
1692 } % end of single compound music expression
1695 (Note how all the statements which open a block with either a
1696 curly bracket, @code{@{}, or double angle brackets, @code{<<},
1697 are indented by two further spaces, and the corresponding
1698 closing bracket is indented by exactly the same amount. While
1699 this is not required, following this practice will greatly
1700 reduce the number of @q{unmatched bracket} errors, and is
1701 strongly recommended. It enables the structure of the music to
1702 be seen at a glance, and any unmatched brackets will be obvious.
1703 Note too how the LH staff is created using double angle brackets
1704 because it requires two voices for its music, whereas the RH staff
1705 is created with a single music expression surrounded by curly
1706 brackets because it requires only one voice.)
1708 @cindex contexts, naming
1709 @cindex naming contexts
1711 The @code{\new} command may also give an identifying name to the
1712 context to distinguish it from other contexts of the same type,
1715 \new @var{type} = @var{id} @var{music-expression}
1718 Note the distinction between the name of the context type,
1719 @code{Staff}, @code{Voice}, etc, and the identifying name of a
1720 particular instance of that type, which can be any sequence of letters
1721 invented by the user. Digits and spaces can also be used in the
1722 identifying name, but then it has to be placed in quotes,
1723 i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
1724 The identifying name is used to
1725 refer back to that particular instance of a context. We saw this in
1726 use in the section on lyrics, see @ref{Voices and vocals}.
1730 Notation Reference: @ruser{Creating contexts}.
1733 @node Engravers explained
1734 @subsection Engravers explained
1738 Every mark on the printed output of a score produced by LilyPond
1739 is produced by an @code{Engraver}. Thus there is an engraver
1740 to print staves, one to print note heads, one for stems, one for
1741 beams, etc, etc. In total there are over 120 such engravers!
1742 Fortunately, for most scores it is not necessary to know about
1743 more than a few, and for simple scores you do not need to know
1746 Engravers live and operate in Contexts. Engravers such as the
1747 @code{Metronome_mark_engraver}, whose action and output apply to the
1748 score as a whole, operate in the highest level context -- the
1749 @code{Score} context.
1751 The @code{Clef_engraver} and @code{Key_engraver} are to be
1752 found in every @code{Staff} Context, as different staves may require
1753 different clefs and keys.
1755 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1756 in every @code{Voice} context, the lowest level context of all.
1758 Each engraver processes the particular objects associated
1759 with its function, and maintains the properties that relate
1760 to that function. These properties, like the properties
1761 associated with contexts, may be modified to change the
1762 operation of the engraver or the appearance of those elements
1763 in the printed score.
1765 Engravers all have compound names formed from words which
1766 describe their function. Just the first word is capitalized,
1767 and the remainder are joined to it with underscores. Thus
1768 the @code{Staff_symbol_engraver} is responsible for creating the
1769 lines of the staff, the @code{Clef_engraver} determines and sets
1770 the pitch reference point on the staff by drawing a clef symbol.
1772 Here are some of the most common engravers together with their
1773 function. You will see it is usually easy to guess the function
1774 from the name, or vice versa.
1776 @multitable @columnfractions .3 .7
1779 @item Accidental_engraver
1780 @tab Makes accidentals, cautionary and suggested accidentals
1785 @item Completion_heads_engraver
1786 @tab Splits notes which cross bar lines
1787 @c The old Dynamic_engraver is deprecated. -jm
1788 @item New_dynamic_engraver
1789 @tab Creates hairpins and dynamic texts
1790 @item Forbid_line_break_engraver
1791 @tab Prevents line breaks if a musical element is still active
1793 @tab Creates the key signature
1794 @item Metronome_mark_engraver
1795 @tab Engraves metronome marking
1796 @item Note_heads_engraver
1797 @tab Engraves note heads
1800 @item Staff_symbol_engraver
1801 @tab Engraves the five (by default) lines of the staff
1803 @tab Creates stems and single-stem tremolos
1804 @item Time_signature_engraver
1805 @tab Creates time signatures
1810 We shall see later how the output of LilyPond can be changed
1811 by modifying the action of Engravers.
1815 Internals reference: @rinternals{Engravers and Performers}.
1818 @node Modifying context properties
1819 @subsection Modifying context properties
1821 @cindex context properties
1822 @cindex context properties, modifying
1823 @cindex modifying context properties
1829 Contexts are responsible for holding the values of a number of
1830 context @emph{properties}. Many of them can be changed to
1831 influence the interpretation of the input and so change the
1832 appearance of the output. They are changed by the
1833 @code{\set} command. This takes the form
1836 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1839 Where the @emph{ContextName} is usually @code{Score},
1840 @code{Staff} or @code{Voice}. It may be omitted,
1841 in which case the current context (typically @code{Voice}) is assumed.
1843 The names of context properties consist of words joined
1844 together with no hyphens or underscores, all except the
1845 first having a capital letter. Here are a few examples
1846 of some commonly used ones. There are many more.
1848 @c attempt to force this onto a new page
1850 @multitable @columnfractions .25 .15 .45 .15
1851 @headitem propertyName
1857 @tab If true, set extra natural signs before accidentals
1858 @tab @code{#t}, @code{#f}
1859 @item currentBarNumber
1861 @tab Set the current bar number
1865 @tab If true, print slurs both above and below notes
1866 @tab @code{#t}, @code{#f}
1867 @item instrumentName
1869 @tab Set the name to be placed at the start of the staff
1870 @tab @code{"Cello I"}
1873 @tab Increase or decrease the font size
1877 @tab Set the text to print before the start of a verse
1882 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1883 an Integer is a positive whole number, a Real is a positive
1884 or negative decimal number, and text is enclosed in double
1885 apostrophes. Note the occurrence of hash signs,
1886 (@code{#}), in two different places -- as part of the Boolean
1887 value before the @code{t} or @code{f}, and before @emph{value}
1888 in the @code{\set} statement. So when a Boolean is being
1889 entered you need to code two hash signs, e.g., @code{##t}.
1891 @cindex properties operating in contexts
1892 @cindex setting properties within contexts
1894 Before we can set any of these properties we need to know
1895 in which context they operate. Sometimes this is obvious,
1896 but occasionally it can be tricky. If the wrong context
1897 is specified, no error message is produced, but the expected
1898 action will not take place. For example, the
1899 @code{instrumentName} clearly lives in the @code{Staff} context, since
1900 it is the staff that is to be named.
1901 In this example the first staff is labelled, but not the second,
1902 because we omitted the context name.
1904 @lilypond[quote,verbatim,ragged-right]
1906 \new Staff \relative c'' {
1907 \set Staff.instrumentName = #"Soprano"
1910 \new Staff \relative c' {
1911 \set instrumentName = #"Alto" % Wrong!
1917 Remember the default context name is @code{Voice}, so the second
1918 @code{\set} command set the property @code{instrumentName} in the
1919 @code{Voice} context to @qq{Alto}, but as LilyPond does not look
1920 for any such property in the @code{Voice} context, no
1921 further action took place. This is not an error, and no error
1922 message is logged in the log file.
1924 Similarly, if the property name is mis-spelt no error message is
1925 produced, and clearly the expected action cannot be performed. In
1926 fact, you can set any (fictitious) @q{property} using any name you
1927 like in any context that exists by using the @code{\set} command. But
1928 if the name is not known to LilyPond it will not cause any action to
1929 be taken. Some text editors with special support for LilyPond input
1930 files document property names with bullets when you hover them with
1931 the mouse, like JEdit with LilyPondTool, or highlight unknown property
1932 names differently, like ConTEXT. If you do not use an editor with
1933 such features, it is recommended to check the property name in the
1934 Internals Reference: see @rinternals{Tunable context properties}, or
1935 @rinternals{Contexts}.
1937 The @code{instrumentName} property will take effect only
1938 if it is set in the @code{Staff} context, but
1939 some properties can be set in more than one context.
1940 For example, the property @code{extraNatural} is by
1941 default set to ##t (true) for all staves.
1942 If it is set to ##f (false) in one particular @code{Staff}
1943 context it applies just to the accidentals on that staff.
1944 If it is set to false in the @code{Score} context
1945 it applies to all staves.
1947 So this turns off extra naturals in one staff:
1949 @lilypond[quote,verbatim,ragged-right]
1951 \new Staff \relative c'' {
1954 \new Staff \relative c'' {
1955 \set Staff.extraNatural = ##f
1962 and this turns them off in all staves:
1964 @lilypond[quote,verbatim,ragged-right]
1966 \new Staff \relative c'' {
1969 \new Staff \relative c'' {
1970 \set Score.extraNatural = ##f
1976 As another example, if @code{clefOctavation} is set in
1977 the @code{Score} context this immediately changes the value
1978 of the octavation in all current staves and sets a new default
1979 value which will be applied to all staves.
1981 The opposite command, @code{\unset}, effectively removes the
1982 property from the context, which causes most properties to
1983 revert to their default value. Usually @code{\unset} is not
1984 required as a new @code{\set} command will achieve what is
1987 The @code{\set} and @code{\unset} commands can appear anywhere
1988 in the input file and will take effect from the time they are
1989 encountered until the end of the score or until the property is
1990 @code{\set} or @code{\unset} again. Let's try changing the
1991 font size, which affects the size of the note heads (among
1992 other things) several times. The change is from the default
1993 value, not the most recently set value.
1995 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1997 % make note heads smaller
2000 % make note heads larger
2001 \set fontSize = #2.5
2003 % return to default size
2008 We have now seen how to set the values of several different types of
2009 property. Note that integers and numbers are always preceded by a
2010 hash sign, @code{#}, while a true or false value is specified by
2011 @code{##t} and @code{##f}, with two hash signs. A text property
2012 should be enclosed in double quotation signs, as above, although we
2013 shall see later that text can actually be specified in a much more
2014 general way by using the very powerful @code{\markup} command.
2016 @subsubheading Setting context properties with @code{\with}
2020 @cindex context properties, setting with \with
2022 The default value of context properties may be set at the time the
2023 context is created. Sometimes this is a clearer way of setting a
2024 property value if it is to remain fixed for the duration of
2025 the context. When a context is created with a @code{\new}
2026 command it may be followed immediately by a @code{\with @{ .. @}}
2027 block in which the default property values are set. For example,
2028 if we wish to suppress the printing of extra naturals for the
2029 duration of a staff we would write:
2032 \new Staff \with @{ extraNatural = ##f @}
2038 @lilypond[quote,verbatim,ragged-right]
2044 \new Staff \with { extraNatural = ##f }
2051 Or, if the property override is to be applied to all staves
2052 within the score, it may be appended to an explicit
2053 @code{\new Score} command, like this:
2055 @lilypond[quote,verbatim,ragged-right]
2057 \new Score \with { extraNatural = ##f } <<
2072 Properties set in this way may still be changed dynamically using
2073 @code{\set} and returned to the default value set in the
2074 @code{\with} block with @code{\unset}.
2076 @cindex fontSize, default and setting
2078 So if the @code{fontSize} property is set in a @code{\with} clause
2079 it sets the default value of the font size. If it is later changed
2080 with @code{\set}, this new default value may be restored with the
2081 @code{\unset fontSize} command.
2083 @subsubheading Setting context properties with @code{\context}
2085 @cindex context properties, setting with \context
2089 The values of context properties may be set in @emph{all} contexts
2090 of a particular type, such as all @code{Staff} contexts, with a single
2091 command. The context type is identified by using its
2092 type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
2093 The statement which sets the property value is the same as that in a
2094 @code{\with} block, introduced above. It is placed in a
2095 @code{\context} block within a @code{\layout} block. Each
2096 @code{\context} block will affect all contexts of the type specified
2097 throughout the @code{\score} or @code{\book} block in which the
2098 @code{\layout} block appears. Here is a example to show the format:
2100 @lilypond[verbatim,quote]
2117 Context properties set in this way may be overridden for particular
2118 instances of contexts by statements in a @code{\with} block, and by
2119 @code{\set} commands embedded in music statements.
2124 @ruser{Changing context default settings}.
2126 @c uncomment when backslash-node-name issue is resolved -pm
2127 @c @ruser{The set command}.
2129 Internals Reference:
2130 @rinternals{Contexts},
2131 @rinternals{Tunable context properties}.
2134 @node Adding and removing engravers
2135 @subsection Adding and removing engravers
2137 @cindex engravers, adding
2138 @cindex adding engravers
2139 @cindex engravers, removing
2140 @cindex removing engravers
2147 We have seen that contexts each contain several engravers, each
2148 of which is responsible for producing a particular part of the
2149 output, like bar lines, staves, note heads, stems, etc. If an
2150 engraver is removed from a context, it can no longer produce its
2151 output. This is a crude way of modifying the output, but it
2152 can sometimes be useful.
2154 @subsubheading Changing a single context
2156 To remove an engraver from a single context we use the
2157 @code{\with} command placed immediately after the context creation
2158 command, as in the previous section.
2160 As an illustration, let's repeat an example from the previous section
2161 with the staff lines removed. Remember that the staff lines are
2162 produced by the @code{Staff_symbol_engraver}.
2164 @lilypond[quote,verbatim,ragged-right]
2166 \remove Staff_symbol_engraver
2170 \set fontSize = #-4 % make note heads smaller
2172 \set fontSize = #2.5 % make note heads larger
2174 \unset fontSize % return to default size
2179 @cindex ambitus engraver
2181 Engravers can also be added to individual contexts.
2182 The command to do this is
2184 @code{\consists @var{Engraver_name}},
2187 placed inside a @code{\with} block. Some vocal scores have an ambitus
2188 placed at the beginning of a staff to indicate the range of notes in
2189 that staff -- see @rglos{ambitus}. The ambitus is produced by the
2190 @code{Ambitus_engraver}, which is not normally included in any
2191 context. If we add it to the @code{Voice} context, it calculates the
2192 range from that voice only:
2194 @lilypond[quote,verbatim,ragged-right]
2197 \consists Ambitus_engraver
2212 but if we add the ambitus engraver to the
2213 @code{Staff} context, it calculates the range from all
2214 the notes in all the voices on that staff:
2216 @lilypond[quote,verbatim,ragged-right]
2218 \consists Ambitus_engraver
2234 @subsubheading Changing all contexts of the same type
2239 The examples above show how to remove or add engravers to
2240 individual contexts. It is also possible to remove or add
2241 engravers to every context of a specific type by placing the
2242 commands in the appropriate context in a @code{\layout}
2243 block. For example, if we wanted to show an ambitus for every
2244 staff in a four-staff score, we could write
2246 @lilypond[quote,verbatim,ragged-right]
2250 \relative c'' { c a b g }
2253 \relative c' { c a b g }
2257 \relative c' { c a b g }
2261 \relative c { c a b g }
2267 \consists Ambitus_engraver
2274 The values of context properties may also be set
2275 for all contexts of a particular type by including the
2276 @code{\set} command in a @code{\context} block in the
2281 Notation Reference: @ruser{Modifying context plug-ins},
2282 @ruser{Changing context default settings}.
2285 @node Extending the templates
2286 @section Extending the templates
2288 You've read the tutorial, you know how to write music, you
2289 understand the fundamental concepts. But how can you
2290 get the staves that you want? Well, you can find lots of
2291 templates (see @ref{Templates}) which may give you a start.
2292 But what if you want something that isn't covered there? Read on.
2295 * Soprano and cello::
2296 * Four-part SATB vocal score::
2297 * Building a score from scratch::
2298 * Saving typing with variables and functions::
2299 * Scores and parts::
2302 @node Soprano and cello
2303 @subsection Soprano and cello
2305 @cindex template, modifying
2306 @cindex modifying templates
2308 Start off with the template that seems closest to what you want to end
2309 up with. Let's say that you want to write something for soprano and
2310 cello. In this case, we would start with the @q{Notes and lyrics} template (for the
2314 \version @w{"@version{}"}
2315 melody = \relative c' @{
2322 text = \lyricmode @{
2328 \new Voice = "one" @{
2332 \new Lyrics \lyricsto "one" \text
2339 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2342 \version @w{"@version{}"}
2343 melody = \relative c' @{
2357 We don't need two @code{\version} commands. We'll need the
2358 @code{melody} section. We don't want two @code{\score} sections
2359 -- if we had two @code{\score}s, we'd get the two parts separately.
2360 We want them together, as a duet. Within the @code{\score}
2361 section, we don't need two @code{\layout} or @code{\midi}.
2363 If we simply cut and paste the @code{melody} section, we would
2364 end up with two @code{melody} definitions. This would not generate
2365 an error, but the second one would be used for both melodies.
2366 So let's rename them to make them distinct. We'll call the
2367 section for the soprano @code{sopranoMusic} and the section for
2368 the cello @code{celloMusic}. While we're doing this, let's rename
2369 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2370 instances of all these names -- both the initial definition (the
2371 @code{melody = \relative c' @{ } part) and the name's use (in the
2372 @code{\score} section).
2374 While we're doing this, let's change the cello part's staff --
2375 celli normally use bass clef. We'll also give the cello some
2379 \version @w{"@version{}"}
2380 sopranoMusic = \relative c' @{
2387 sopranoLyrics = \lyricmode @{
2391 celloMusic = \relative c @{
2400 \new Voice = "one" @{
2404 \new Lyrics \lyricsto "one" \sopranoLyrics
2411 This is looking promising, but the cello part won't appear in the
2412 score -- we haven't used it in the @code{\score} section. If we
2413 want the cello part to appear under the soprano part, we need to add
2416 \new Staff \celloMusic
2420 underneath the soprano stuff. We also need to add @code{<<} and
2421 @code{>>} around the music -- that tells LilyPond that there's
2422 more than one thing (in this case, two @code{Staves}) happening
2423 at once. The @code{\score} looks like this now:
2425 @c Indentation in this example is deliberately poor
2430 \new Voice = "one" @{
2434 \new Lyrics \lyricsto "one" \sopranoLyrics
2436 \new Staff \celloMusic
2444 This looks a bit messy; the indentation is messed up now. That is
2445 easily fixed. Here's the complete soprano and cello template.
2447 @lilypond[quote,verbatim,ragged-right,addversion]
2448 sopranoMusic = \relative c' {
2455 sopranoLyrics = \lyricmode {
2459 celloMusic = \relative c {
2469 \new Voice = "one" {
2473 \new Lyrics \lyricsto "one" \sopranoLyrics
2475 \new Staff \celloMusic
2484 The starting templates can be found in the @q{Templates} appendix,
2485 see @ref{Single staff}.
2488 @node Four-part SATB vocal score
2489 @subsection Four-part SATB vocal score
2491 @cindex template, SATB
2492 @cindex SATB template
2494 Most vocal scores of music written for four-part mixed choir
2495 with orchestral accompaniment such as Mendelssohn's Elijah or
2496 Handel's Messiah have the choral music and words on four
2497 staves, one for each of SATB, with a piano reduction of the
2498 orchestral accompaniment underneath. Here's an example
2499 from Handel's Messiah:
2501 @c The following should appear as music without code
2502 @lilypond[quote,ragged-right]
2503 global = { \key d \major \time 4/4 }
2504 sopranoMusic = \relative c'' {
2506 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2508 sopranoWords = \lyricmode {
2509 Wor -- thy is the lamb that was slain
2511 altoMusic = \relative a' {
2513 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
2515 altoWords = \sopranoWords
2516 tenorMusic = \relative c' {
2518 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2520 tenorWords = \sopranoWords
2521 bassMusic = \relative c' {
2523 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2525 bassWords = \sopranoWords
2526 upper = \relative a' {
2529 r4 <a d fis>2 <a e' a>4 |
2530 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2531 <g cis g'>4 <a d fis> <a cis e>2 |
2533 lower = \relative c, {
2536 <d d'>4 <d d'>2 <cis cis'>4 |
2537 <b b'>4. <b' b'>8 <fis fis'>2 |
2538 <e e'>4 <d d'> <a' a'>2 |
2542 << % combine ChoirStaff and PianoStaff in parallel
2544 \new Staff = "sopranos" <<
2545 \set Staff.instrumentName = #"Soprano"
2546 \new Voice = "sopranos" { \global \sopranoMusic }
2548 \new Lyrics \lyricsto "sopranos" { \sopranoWords }
2549 \new Staff = "altos" <<
2550 \set Staff.instrumentName = #"Alto"
2551 \new Voice = "altos" { \global \altoMusic }
2553 \new Lyrics \lyricsto "altos" { \altoWords }
2554 \new Staff = "tenors" <<
2555 \set Staff.instrumentName = #"Tenor"
2556 \new Voice = "tenors" { \global \tenorMusic }
2558 \new Lyrics \lyricsto "tenors" { \tenorWords }
2559 \new Staff = "basses" <<
2560 \set Staff.instrumentName = #"Bass"
2561 \new Voice = "basses" { \global \bassMusic }
2563 \new Lyrics \lyricsto "basses" { \bassWords }
2567 \set PianoStaff.instrumentName = #"Piano"
2568 \new Staff = "upper" \upper
2569 \new Staff = "lower" \lower
2575 None of the templates provides this layout exactly. The nearest is
2576 @q{SATB vocal score and automatic piano reduction} -- see @ref{Vocal
2577 ensembles} -- but we need to change the layout and add a piano
2578 accompaniment which is not derived automatically from the vocal parts.
2579 The variables holding the music and words for the vocal parts are
2580 fine, but we shall need to add variables for the piano reduction.
2582 The order in which the contexts appear in the ChoirStaff of the
2583 template do not correspond with the order in the vocal score shown
2584 above. We need to rearrange them so there are four staves with the
2585 words written directly underneath the notes for each part. All the
2586 voices should be @code{\voiceOne}, which is the default, so the
2587 @code{\voiceXXX} commands should be removed. We also need to specify
2588 the tenor clef for the tenors. The way in which lyrics are specified
2589 in the template has not yet been encountered so we need to use the
2590 method with which we are familiar. We should also add the names of
2593 Doing this gives for our ChoirStaff:
2597 \new Staff = "sopranos" <<
2598 \set Staff.instrumentName = #"Soprano"
2599 \new Voice = "sopranos" @{ \global \sopranoMusic @}
2601 \new Lyrics \lyricsto "sopranos" @{ \sopranoWords @}
2602 \new Staff = "altos" <<
2603 \set Staff.instrumentName = #"Alto"
2604 \new Voice = "altos" @{ \global \altoMusic @}
2606 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2607 \new Staff = "tenors" <<
2608 \set Staff.instrumentName = #"Tenor"
2609 \new Voice = "tenors" @{ \global \tenorMusic @}
2611 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2612 \new Staff = "basses" <<
2613 \set Staff.instrumentName = #"Bass"
2614 \new Voice = "basses" @{ \global \bassMusic @}
2616 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2620 Next we must work out the piano part. This is
2621 easy - we just pull out the piano part from the
2622 @q{Solo piano} template:
2626 \set PianoStaff.instrumentName = #"Piano "
2627 \new Staff = "upper" \upper
2628 \new Staff = "lower" \lower
2632 and add the variable definitions for @code{upper}
2635 The ChoirStaff and PianoStaff must be combined
2636 using angle brackets as we want them to be
2637 stacked one above the other:
2640 << % combine ChoirStaff and PianoStaff one above the other
2642 \new Staff = "sopranos" <<
2643 \new Voice = "sopranos" @{ \global \sopranoMusic @}
2645 \new Lyrics \lyricsto "sopranos" @{ \sopranoWords @}
2646 \new Staff = "altos" <<
2647 \new Voice = "altos" @{ \global \altoMusic @}
2649 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2650 \new Staff = "tenors" <<
2651 \clef "G_8" % tenor clef
2652 \new Voice = "tenors" @{ \global \tenorMusic @}
2654 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2655 \new Staff = "basses" <<
2657 \new Voice = "basses" @{ \global \bassMusic @}
2659 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2663 \set PianoStaff.instrumentName = #"Piano"
2664 \new Staff = "upper" \upper
2665 \new Staff = "lower" \lower
2670 Combining all these together and adding the music
2671 for the three bars of the example above gives:
2673 @lilypond[quote,verbatim,ragged-right,addversion]
2674 global = { \key d \major \time 4/4 }
2675 sopranoMusic = \relative c'' {
2677 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2679 sopranoWords = \lyricmode {
2680 Wor -- thy is the lamb that was slain
2682 altoMusic = \relative a' {
2684 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2686 altoWords = \sopranoWords
2687 tenorMusic = \relative c' {
2689 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2691 tenorWords = \sopranoWords
2692 bassMusic = \relative c' {
2694 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2696 bassWords = \sopranoWords
2697 upper = \relative a' {
2700 r4 <a d fis>2 <a e' a>4 |
2701 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2702 <g cis g'>4 <a d fis> <a cis e>2 |
2704 lower = \relative c, {
2707 <d d'>4 <d d'>2 <cis cis'>4 |
2708 <b b'>4. <b' b'>8 <fis fis'>2 |
2709 <e e'>4 <d d'> <a' a'>2 |
2713 << % combine ChoirStaff and PianoStaff in parallel
2715 \new Staff = "sopranos" <<
2716 \set Staff.instrumentName = #"Soprano"
2717 \new Voice = "sopranos" { \global \sopranoMusic }
2719 \new Lyrics \lyricsto "sopranos" { \sopranoWords }
2720 \new Staff = "altos" <<
2721 \set Staff.instrumentName = #"Alto"
2722 \new Voice = "altos" { \global \altoMusic }
2724 \new Lyrics \lyricsto "altos" { \altoWords }
2725 \new Staff = "tenors" <<
2726 \set Staff.instrumentName = #"Tenor"
2727 \new Voice = "tenors" { \global \tenorMusic }
2729 \new Lyrics \lyricsto "tenors" { \tenorWords }
2730 \new Staff = "basses" <<
2731 \set Staff.instrumentName = #"Bass"
2732 \new Voice = "basses" { \global \bassMusic }
2734 \new Lyrics \lyricsto "basses" { \bassWords }
2738 \set PianoStaff.instrumentName = #"Piano "
2739 \new Staff = "upper" \upper
2740 \new Staff = "lower" \lower
2747 @node Building a score from scratch
2748 @subsection Building a score from scratch
2750 @cindex template, writing your own
2751 @cindex example of writing a score
2752 @cindex writing a score, example
2753 @cindex score, example of writing
2755 After gaining some facility with writing LilyPond code, you
2756 may find that it is easier to build a score from scratch
2757 rather than modifying one of the templates. You can also
2758 develop your own style this way to suit the sort of music you
2759 like. Let's see how to put together the score for an organ
2760 prelude as an example.
2762 We begin with a header section. Here go the title, name
2763 of composer, etc, then come any variable definitions, and
2764 finally the score block. Let's start with these in outline
2765 and fill in the details later.
2767 We'll use the first two bars of Bach's prelude
2768 based on @emph{Jesu, meine Freude} which is written for two
2769 manuals and pedal organ. You can see these two bars of music
2770 at the bottom of this section. The top manual part has two voices,
2771 the lower and pedal organ one each. So we need four
2772 music definitions and one to define the time signature
2776 \version @w{"@version{}"}
2778 title = "Jesu, meine Freude"
2779 composer = "J S Bach"
2781 TimeKey = @{ \time 4/4 \key c \minor @}
2782 ManualOneVoiceOneMusic = @{s1@}
2783 ManualOneVoiceTwoMusic = @{s1@}
2784 ManualTwoMusic = @{s1@}
2785 PedalOrganMusic = @{s1@}
2791 For now we've just used a spacer note, @code{s1},
2792 instead of the real music. We'll add that later.
2794 Next let's see what should go in the score block.
2795 We simply mirror the staff structure we want.
2796 Organ music is usually written on three staves,
2797 one for each manual and one for the pedals. The
2798 manual staves should be bracketed together, so we
2799 need to use a PianoStaff for them. The first
2800 manual part needs two voices and the second manual
2805 \new Staff = "ManualOne" <<
2806 \new Voice @{ \ManualOneVoiceOneMusic @}
2807 \new Voice @{ \ManualOneVoiceTwoMusic @}
2808 >> % end ManualOne Staff context
2809 \new Staff = "ManualTwo" <<
2810 \new Voice @{ \ManualTwoMusic @}
2811 >> % end ManualTwo Staff context
2812 >> % end PianoStaff context
2815 Next we need to add a staff for the pedal organ.
2816 This goes underneath the PianoStaff, but it must
2817 be simultaneous with it, so we need angle brackets
2818 around the two. Missing these out would generate
2819 an error in the log file. It's a common mistake
2820 which you'll make sooner or later! Try copying
2821 the final example at the end of this section,
2822 remove these angle brackets, and compile it to
2823 see what errors it generates.
2826 << % PianoStaff and Pedal Staff must be simultaneous
2828 \new Staff = "ManualOne" <<
2829 \new Voice @{ \ManualOneVoiceOneMusic @}
2830 \new Voice @{ \ManualOneVoiceTwoMusic @}
2831 >> % end ManualOne Staff context
2832 \new Staff = "ManualTwo" <<
2833 \new Voice @{ \ManualTwoMusic @}
2834 >> % end ManualTwo Staff context
2835 >> % end PianoStaff context
2836 \new Staff = "PedalOrgan" <<
2837 \new Voice @{ \PedalOrganMusic @}
2842 It is not necessary to use the simultaneous construct
2843 @code{<< .. >>} for the manual two staff and the pedal organ staff,
2844 since they contain only one music expression, but it does no harm,
2845 and always using angle brackets after @code{\new Staff} is a good
2846 habit to cultivate in case there are multiple voices. The opposite
2847 is true for Voices: these should habitually be followed by braces
2848 @code{@{ .. @}} in case your music is coded in several variables
2849 which need to run consecutively.
2851 Let's add this structure to the score block, and adjust the indenting.
2852 We also add the appropriate clefs, ensure stems, ties and slurs in
2853 each voice on the upper staff point to the right direction with
2854 @code{\voiceOne} and @code{\voiceTwo}, and enter the time signature
2855 and key to each staff using our predefined variable, @code{\TimeKey}.
2859 << % PianoStaff and Pedal Staff must be simultaneous
2861 \new Staff = "ManualOne" <<
2862 \TimeKey % set time signature and key
2864 \new Voice @{ \voiceOne \ManualOneVoiceOneMusic @}
2865 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2866 >> % end ManualOne Staff context
2867 \new Staff = "ManualTwo" <<
2870 \new Voice @{ \ManualTwoMusic @}
2871 >> % end ManualTwo Staff context
2872 >> % end PianoStaff context
2873 \new Staff = "PedalOrgan" <<
2876 \new Voice @{ \PedalOrganMusic @}
2877 >> % end PedalOrgan Staff
2879 @} % end Score context
2882 That completes the structure. Any three-staff organ music
2883 will have a similar structure, although the number of voices
2884 may vary. All that remains now
2885 is to add the music, and combine all the parts together.
2887 @lilypond[quote,verbatim,ragged-right,addversion]
2889 title = "Jesu, meine Freude"
2890 composer = "J S Bach"
2892 TimeKey = { \time 4/4 \key c \minor }
2893 ManualOneVoiceOneMusic = \relative g' {
2894 g4 g f ees | d2 c2 |
2896 ManualOneVoiceTwoMusic = \relative c' {
2897 ees16 d ees8~ ees16 f ees d c8 d~ d c~ |
2898 c c4 b8 c8. g16 c b c d |
2900 ManualTwoMusic = \relative c' {
2901 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2902 f ees f d g aes g f ees d e8~ ees16 f ees d |
2904 PedalOrganMusic = \relative c {
2905 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2906 r16 g ees f g f g8 c,2 |
2910 << % PianoStaff and Pedal Staff must be simultaneous
2912 \new Staff = "ManualOne" <<
2913 \TimeKey % set time signature and key
2915 \new Voice { \voiceOne \ManualOneVoiceOneMusic }
2916 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2917 >> % end ManualOne Staff context
2918 \new Staff = "ManualTwo" <<
2921 \new Voice { \ManualTwoMusic }
2922 >> % end ManualTwo Staff context
2923 >> % end PianoStaff context
2924 \new Staff = "PedalOrgan" <<
2927 \new Voice { \PedalOrganMusic }
2928 >> % end PedalOrgan Staff context
2930 } % end Score context
2934 @node Saving typing with variables and functions
2935 @subsection Saving typing with variables and functions
2940 By this point, you've seen this kind of thing:
2942 @lilypond[quote,verbatim,ragged-right]
2943 hornNotes = \relative c'' { c4 b dis c }
2951 You may even realize that this could be useful in minimalist music:
2953 @lilypond[quote,verbatim,ragged-right]
2954 fragmentA = \relative c'' { a4 a8. b16 }
2955 fragmentB = \relative c'' { a8. gis16 ees4 }
2956 violin = \new Staff { \fragmentA \fragmentA \fragmentB \fragmentA }
2964 However, you can also use these variables (also known as
2965 macros, or user-defined commands) for tweaks:
2967 @c TODO Avoid padtext - not needed with skylining
2968 @lilypond[quote,verbatim,ragged-right]
2969 dolce = \markup{ \italic \bold dolce }
2970 padText = { \once \override TextScript #'padding = #5.0 }
2971 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
2972 violin = \relative c'' {
2974 c4._\dolce b8 a8 g a b |
2976 c4.^"hi there!" d8 e' f g d |
2977 c,4.\fthenp b8 c4 c-. |
2984 \layout{ragged-right=##t}
2988 These variables are obviously useful for saving
2989 typing. But they're worth considering even if you
2990 only use them once -- they reduce complexity. Let's
2991 look at the previous example without any
2992 variables. It's a lot harder to read, especially
2996 violin = \relative c'' @{
2998 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
2999 \once \override TextScript #'padding = #5.0
3000 c4.^"hi there!" d8 e' f g d |
3001 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
3002 \hspace #0.1 \dynamic p @} b8 c4 c-. |
3007 @c TODO Replace the following with a better example -td
3008 @c Skylining handles this correctly without padText
3010 So far we've seen static substitution -- when LilyPond
3011 sees @code{\padText}, it replaces it with the stuff that
3012 we've defined it to be (ie the stuff to the right of
3015 LilyPond can handle non-static substitution, too (you
3016 can think of these as functions).
3018 @lilypond[quote,verbatim,ragged-right]
3020 #(define-music-function (parser location padding) (number?)
3022 \once \override TextScript #'padding = #$padding
3026 c4^"piu mosso" b a b
3028 c4^"piu mosso" d e f
3030 c4^"piu mosso" fis a g
3034 Using variables is also a good way to reduce work if the
3035 LilyPond input syntax changes (see
3036 @rprogram{Updating files with convert-ly}). If
3037 you have a single definition (such as @code{\dolce}) for all your
3038 input files (see @ref{Style sheets}), then if the syntax changes, you
3039 only need to update your single @code{\dolce} definition,
3040 instead of making changes throughout every @code{.ly} file.
3043 @node Scores and parts
3044 @subsection Scores and parts
3046 In orchestral music, all notes are printed twice. Once in a part for
3047 the musicians, and once in a full score for the conductor. Variables can
3048 be used to avoid double work. The music is entered once, and stored in
3049 a variable. The contents of that variable is then used to generate
3050 both the part and the full score.
3052 It is convenient to define the notes in a special file. For example,
3053 suppose that the file @file{horn-music.ly} contains the following part
3054 of a horn/@/bassoon duo
3057 hornNotes = \relative c @{
3064 Then, an individual part is made by putting the following in a file
3067 \include "horn-music.ly"
3069 instrument = "Horn in F"
3073 \transpose f c' \hornNotes
3080 \include "horn-music.ly"
3084 substitutes the contents of @file{horn-music.ly} at this position in
3085 the file, so @code{hornNotes} is defined afterwards. The command
3086 @code{\transpose f@tie{}c'} indicates that the argument, being
3087 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
3088 @code{f} is denoted by notated @code{c'}, which corresponds with the
3089 tuning of a normal French Horn in@tie{}F. The transposition can be seen
3090 in the following output
3092 @lilypond[quote,ragged-right]
3093 \transpose f c' \relative c {
3099 In ensemble pieces, one of the voices often does not play for many
3100 measures. This is denoted by a special rest, the multi-measure
3101 rest. It is entered with a capital @code{R} followed by a duration
3102 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
3103 etc.). By multiplying the
3104 duration, longer rests can be constructed. For example, this rest
3105 takes 3@tie{}measures in 2/4 time
3111 When printing the part, multi-rests
3112 must be condensed. This is done by setting a run-time variable
3115 \set Score.skipBars = ##t
3119 This command sets the property @code{skipBars} in the
3120 @code{Score} context to true (@code{##t}). Prepending the rest and
3121 this option to the music above, leads to the following result
3123 @lilypond[quote,ragged-right]
3124 \transpose f c' \relative c {
3126 \set Score.skipBars = ##t
3133 The score is made by combining all of the music together. Assuming
3134 that the other voice is in @code{bassoonNotes} in the file
3135 @file{bassoon-music.ly}, a score is made with
3138 \include "bassoon-music.ly"
3139 \include "horn-music.ly"
3142 \new Staff \hornNotes
3143 \new Staff \bassoonNotes
3150 @lilypond[quote,ragged-right]
3158 r4 d,8 f | gis4 c | b bes |
3159 a8 e f4 | g d | gis f