1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 @node Fundamental concepts
5 @chapter Fundamental concepts
8 * How LilyPond files work::
9 * Voices contain music::
10 * TODO new sec fundamental::
11 * Extending the templates::
16 @node How LilyPond files work
17 @section How LilyPond files work
19 The LilyPond input format is quite free-form, giving experienced
20 users a lot of flexibility to structure their files however they
21 wish. However, this flexibility can make things confusing for new
22 users. This section will explain some of this structure, but may
23 gloss over some details in favor of simplicity. For a complete
24 description of the input format, see @ruser{File structure}.
27 * Introduction to the LilyPond file structure::
28 * Score is a (single) compound musical expression::
29 * Expressions can be nested after the beginning::
32 @node Introduction to the LilyPond file structure
33 @subsection Introduction to the LilyPond file structure
35 A basic example of a lilypond input file is
40 @var{...compound music expression...} % all the music goes here!
48 There are many variations of this basic pattern, but this
49 example serves as a useful starting place.
51 At this point, you may be confused, since you have never seen a
52 @code{\score@{@}} before. This is because LilyPond automatically
53 adds the extra commands when you give it simple input. LilyPond
54 treats input like this:
63 as shorthand for this:
74 In other words, if the input contains a single music expression,
75 LilyPond will interpret the file as though the music expression
76 was wrapped up inside a @code{\score@{@}}.
80 A @code{\score} must begin with a compound music expression.
81 Remember that a music expression could be anything from a single
87 @var{...insert the whole score of a Wagner opera in here...}
93 Since everything is inside @code{@{ ... @}}, it counts
94 as one music expression.
96 As we saw previously, the @code{\score} can contain other things,
109 Some people put some of those commands outside the @code{\score}
110 block -- for example, @code{\header} is often placed above the
111 @code{\score}. That's just another shorthand that LilyPond
118 Another great shorthand is the ability to define variables. All
119 the templates use this
122 melody = \relative c' @{
131 When LilyPond looks at this file, it takes the value of
132 @code{melody} (everything after the equals sign) and inserts it
133 whenever it sees @code{\melody}. There's nothing special about
134 the names -- it could be @code{melody}, @code{global},
135 @code{pianorighthand}, or @code{foofoobarbaz}. You can use
136 whatever variable names you want. For more details, see
137 @ruser{Saving typing with variables and functions}.
142 For a complete definition of the input format, see @ruser{File
146 @node Score is a (single) compound musical expression
147 @subsection Score is a (single) compound musical expression
149 @cindex Compound music expression
150 @cindex Music expression, compound
152 We saw the general organization of LilyPond input files in the
153 previous section, @ref{How LilyPond files work}. But we seemed to
154 skip over the most important part: how do we figure out what to
155 write after @code{\score}?
157 We didn't skip over it at all. The big mystery is simply that
158 there @emph{is} no mystery. This line explains it all:
161 @emph{A @code{\score} must begin with a compound music expression.}
165 You may find it useful to review @ref{Music expressions
166 explained}. In that section, we saw how to build big music
167 expressions from small pieces -- we started from notes, then
168 chords, etc. Now we're going to start from a big music expression
169 and work our way down.
173 @{ % this brace begins the overall compound music expression
175 @var{...insert the whole score of a Wagner opera in here...}
177 @} % this brace ends the overall compound music expression
182 A whole Wagner opera would easily double the length of this
183 manual, so let's just add a singer and piano. We don't need a
184 @code{GrandStaff} for this ensemble, so we shall remove it. We
185 @emph{do} need a singer and a piano, though.
191 \new Staff = "singer" <<
193 \new PianoStaff = piano <<
201 Remember that we use @code{<<} and @code{>>} to show concurrent
202 music. And we definitely want to show the vocal part and piano
203 part at the same time, not one after the other!
209 \new Staff = "singer" <<
210 \new Voice = "vocal" @{ @}
212 \new Lyrics \lyricsto vocal \new Lyrics @{ @}
213 \new PianoStaff = "piano" <<
214 \new Staff = "upper" @{ @}
215 \new Staff = "lower" @{ @}
223 Now we have a lot more details. We have the singer's staff: it
224 contains a @code{Voice} (in LilyPond, this term refers to a set of
225 notes, not necessarily vocal notes -- for example, a violin
226 generally plays one voice) and some lyrics. We also have a piano
227 staff: it contains an upper staff (right hand) and a lower staff
230 At this stage, we could start filling in notes. Inside the curly
231 braces next to @code{\new Voice = vocal}, we could start writing
239 But if we did that, the @code{\score} section would get pretty
240 long, and it would be harder to understand what was happening. So
241 let's use variables instead.
251 \new Staff = "singer" <<
252 \new Voice = "vocal" @{ \melody @}
254 \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
255 \new PianoStaff = "piano" <<
256 \new Staff = "upper" @{ \upper @}
257 \new Staff = "lower" @{ \lower @}
266 Remember that you can use almost any name you like as long
267 as it contains just alphabetic characters. The exact
268 limitations on variable names are detailed in @ruser{File
271 When writing (or reading) a @code{\score} section, just take it
272 slowly and carefully. Start with the outer layer, then work on
273 each smaller layer. It also really helps to be strict with
274 indentation -- make sure that each item on the same layer starts
275 on the same horizontal position in your text editor.
278 @node Expressions can be nested after the beginning
279 @subsection Expressions can be nested after the beginning
281 TODO: this title is teh suck. :(
283 @lilypond[verbatim,quote,ragged-right]
286 \new Staff \relative c''{ c1 c c c c }
287 \new StaffGroup \relative c''{
290 << c1 \new Staff { c1 } >>
305 @node Voices contain music
306 @section Voices contain music
308 TODO: something cheesy and vaguely witty about voices being the
309 fundamental thing that includes music in lilypond.
312 * I'm hearing Voices::
313 * Explicitly instantiating voices::
314 * Voices and vocals::
317 @node I'm hearing Voices
318 @subsection I'm hearing Voices
322 @cindex Voice context
324 The lowest, most fundamental or innermost layers in a LilyPond
325 score are called Voices. Voices are sometimes
326 called @q{layers} in other notation packages. In LilyPond they
327 are called @q{Voice contexts}.
329 In fact, a Voice layer or context is the only one which can
330 contain music. If a Voice context is not explicitly declared
331 one is created automatically. Some instruments such as an
332 Oboe can play only one note at a time and music written for
333 such instruments is monophonic and requires just a single
334 voice. Instruments which can play more than one note at a
335 time like the piano will often require multiple voices to
336 encode the different concurent notes and rhythms they are
339 A single voice can contain many notes in a chord, of course,
340 so when exactly are multiple voices needed?
341 Let us analyse a short piece of music to see how many voices
342 are required. Here are the notes from the first two bars
343 of the second of Chopin's Deux Nocturnes, Op 32.
345 @c The following should appear as music without code
346 @lilypond[quote,ragged-right]
347 \new Staff \relative c'' {
355 \once \override NoteColumn #'force-hshift = #0 <ees c>2
356 \once \override NoteColumn #'force-hshift = #0.5 des2 }
362 The direction of the stems is often used to indicate the
363 continuity of two concurrent melodic lines. Here the
364 stems of the highest notes are all pointing up and the
365 stems of the lower notes are all pointing down.
366 This is the first indication that more than one voice
369 But the real need for multiple voices arises when notes
370 which start at the same time have different durations.
371 Look at the notes which start at beat three in the first
372 bar. The a-flat is a dotted quarter note, the f is a
373 quarter note and the d-flat is a half note. These
374 cannot be written as a chord as all the notes in a chord
375 must have the same duration. Neither can they be written
376 as sequential notes, as they must start at the same time.
377 This section of the bar requires three voices, and the
378 normal practice would be to write the whole bar as three
379 voices, as shown here, where we have coloured the three
382 @c The following should appear as music without code
383 @lilypond[quote,ragged-right]
384 \new Staff \relative c'' {
388 \override NoteHead #'color = #red
389 \override Stem #'color = #red
392 \override NoteHead #'color = #blue
393 \override Stem #'color = #blue
396 \override NoteHead #'color = #green
397 \override Stem #'color = #green
398 \once \override NoteColumn #'force-hshift = #0 <ees c>2
399 \once \override NoteColumn #'force-hshift = #0.5 des2 }
405 Let us see how this is done.
409 The easiest way to enter fragments with more than one voice on a
410 staff is to enter each voice as a sequence (with @code{@{...@}}),
411 and combine them concurrently with angle brackets, @code{<<...>>}.
412 The fragments must also be separated with double backward slashes,
413 @code{\\}, to place them in separate voices. Without these, the
414 notes would be entered into a single voice, which would usually
415 cause errors. This technique is particularly suited to pieces of
416 music which are largely monophonic with occasional short sections
417 of polyphony. Here's a simple example:
419 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
421 % Voice "1" Voice "2"
422 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
423 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
424 << { a2. r4 } \\ { fis2. s4 } >>
427 This example has just two voices, but the same contruct may be
428 used to encode three or more voices by adding more back-slash
431 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
432 In each of these contexts, vertical direction of slurs, stems, ties,
433 dynamics etc., is set appropriately.
435 @lilypond[quote,verbatim,fragment]
436 \new Staff \relative c' {
439 % Voice "1" Voice "2" Voice "3"
440 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
441 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
445 These voices are all separate from the main voice that contains
446 the notes just outside the @code{<< \\ >>} construct. Slurs and
447 ties may only connect notes within the same voice, so
448 slurs and ties cannot go into or out of a @code{<< \\ >>}
449 construct. Conversely, parallel voices from separate @code{<< \\
450 >>} constructs on the same staff are the same voice. Other voice-
451 related properties also carry across @code{<< \\ >>} constructs.
453 same example, with different colors for each voice.
454 Note that changing the colour of the main voice to red does
455 not affect the inside of the @code{<< \\ >>} constructs. Also,
456 changing the colour of the second voice to blue in the first
457 @code{<< \\ >>} construct is effective in the second
458 @code{<< \\ >>} construct. Note that tied notes may be split
459 across the same voices in two constructs, shown here in the
462 @cindex notehead colour
467 TODO: Consider whether to retain the style changes - I think they
468 spoil the appearance, so I've commented them out. If we are
469 to retain colour, I'd prefer to colour the stems and beams
471 TODO: Check that these color overrides have been introduced
472 earlier in the LM. -td
474 @lilypond[quote,verbatim,fragment]
475 \new Staff \relative c' {
476 % \override NoteHead #'style = #'cross
477 \override NoteHead #'color = #red
478 \override Stem #'color = #red
479 \override Beam #'color = #red
484 % \override NoteHead #'style = #'triangle
485 \override NoteHead #'color = #blue
486 \override Stem #'color = #blue
487 \override Beam #'color = #blue
493 { c8 b16 a b8 g ~ g2 } \\
495 % \override NoteHead #'style = #'slash
496 \override NoteHead #'color = #green
497 \override Stem #'color = #green
498 \override Beam #'color = #green
505 Polyphony does not change the relationship of notes within a
506 @code{\relative @{ @}} block. Each note is calculated relative to
507 the note immediately preceding it, or to the first note of the
511 \relative @{ noteA << <noteB noteC> \\ noteD >> noteE @}
514 @code{noteB} is relative to @code{noteA}
515 @code{noteC} is relative to @code{noteB}, not @code{noteA};
516 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
518 @code{noteE} is relative to @code{noteD}, not @code{noteA}
520 We are now in a position to return to the first example from
521 the Chopin Nocturne to see how this might be encoded. As we
522 shall see, this encounters some difficulties. We begin as
523 we have learnt, using the @code{<< \\ >>} construct to
524 enter the music of the first bar in three voices:
526 @lilypond[quote,verbatim,fragment,ragged-right]
527 \new Staff \relative c'' {
530 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
541 The stem directions are automatically assigned with the
542 odd-numbered voices taking upward stems and the even-numbered
543 voices downward ones. The stems for voices 1 and 2 are right,
544 but the stems in voice 3 should go down in this particular piece
545 of music. We can correct this
546 by using the @code{\stemDown} command. There is also a
547 corresponding @code{\stemUp} command. These may be used
548 in any music stream to change the direction of the stems
549 of the following notes. Let's use @code{\stemDown} to
550 correct our third voice. This result in the following:
552 @lilypond[quote,verbatim,fragment,ragged-right]
553 \new Staff \relative c'' {
558 { \stemDown <ees c>2 des2 }
565 and exposes a problem commonly encountered with multiple
566 voices: the stems of notes can collide with noteheads
567 in other voices. In laying out the notes, LilyPond allows the
568 notes or chords from two voices to occupy the same vertical
569 note column provided the stems are in opposite directions, but
570 the notes from a third voice are displaced to avoid the stems
571 colliding. This often works well, but in this example the
572 notes of the third voice are clearly not well placed by default.
573 LilyPond provides several ways to adjust the horizontal placing
574 of notes. These are described in the Notation Reference.
575 We introduce just one here, the @code{force-hshift} property of
576 @code{NoteColumn}. The lower two notes of the first chord (i.e,
577 those in the third voice) should not be shifted away from the
578 note column of the higher two notes. To correct this we set
579 @code{force-hshift} of these notes to zero.
580 The lower note of the second chord is best placed just to the
581 right of the higher notes. We achieve this by setting
582 @code{force-hshift} of this note to 0.5, ie half a notehead's
583 width to the right of the note column of the higher notes.
585 Here's the final result:
587 @lilypond[quote,verbatim,fragment,ragged-right]
588 \new Staff \relative c'' {
594 \once \override NoteColumn #'force-hshift = #0 <ees c>2
595 \once \override NoteColumn #'force-hshift = #0.5 des2
602 @node Explicitly instantiating voices
603 @subsection Explicitly instantiating voices
605 Voice contexts can also be created manually
606 inside a @code{<< >>} block to create polyphonic music, using
607 @code{\voiceOne}, up to @code{\voiceFour} to automatically assign
608 the directions of stems, slurs, etc.
610 Specifically, the construct @code{<< \\ >>} which we used in
611 the previous section:
614 << \upper \\ \lower >>
618 where @code{upper} and @code{lower} are user-defined variables
619 containing the music for the two voices, is equivalent to
623 \new Voice = "1" @{ \voiceOne \upper @}
624 \new Voice = "2" @{ \voiceTwo \lower @}
628 The @code{\voiceXXX} commands set the direction of stems, slurs,
629 ties, articulations, text annotations, augmentation dots of dotted
630 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
631 make these objects point upwards, while @code{\voiceTwo} and
632 @code{\voiceFour} make them point downwards. These commands also
633 generate a horizontal shift for each voice when this is required
634 to avoid clashes of note heads. The command @code{\oneVoice}
635 reverts the settings back to the normal values for a single voice.
637 An expression that appears directly inside a @code{<< >>} belongs
638 to the main voice. This is useful when extra voices appear while
639 the main voice is playing. Here is a more correct rendition of
640 the example from the previous section. The red-coloured
641 notes demonstrate that the main melody is now in a single
642 voice context, permitting a phrasing slur to be drawn over them.
644 @lilypond[quote,ragged-right,verbatim]
645 \new Staff \relative c' {
646 \override NoteHead #'color = #red
647 \override Stem #'color = #red
648 \override Beam #'color = #red
649 c16^( d e f % These notes are monophonic
650 << % Start concurrent section of three voices
651 { g4 f e | d2 e2) } % Continue the main voice in parallel
652 \new Voice { % Initiate second voice
653 \voiceTwo % Set stems, etc, down
654 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
656 \new Voice { % Initiate third voice
657 \voiceThree % Set stems, etc, up
664 @cindex nesting music expressions
665 @cindex nesting concurrent constructs
667 More deeply nested polyphony constructs are possible, and if a
668 voice appears only briefly this might be a more natural way to
671 @lilypond[quote,ragged-right,verbatim]
672 \new Staff \relative c' {
692 This method of nesting new voices briefly is useful
693 when only small sections of the music
694 are polyphonic, but when the whole staff is largely polyphonic
695 it can be clearer to use multiple voices throughout and use
696 spacing notes to step over sections where the voice is silent,
699 @lilypond[quote,ragged-right,verbatim]
700 \new Staff \relative c' <<
701 \new Voice { % Initiate first voice
703 c16^( d e f g4 f e | d2 e2) |
705 \new Voice { % Initiate second voice
706 \voiceTwo % set stems, etc down
707 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
709 \new Voice { % Initiate third voice
710 \voiceThree % set stems, etc up
718 @node Voices and vocals
719 @subsection Voices and vocals
721 Vocal music presents a special difficulty: we need to combine two
722 expressions -- notes and lyrics.
724 You have already seen the @code{\lyricsAdd@{@}} command, which
725 handles simple cases for you. However, @code{\lyricsAdd@{@}} is
726 very limited. For most music, you must explicitly link the lyrics
727 to the notes with @code{\lyricsTo@{@}}
729 @lilypond[quote,verbatim,fragment]
731 \new Voice = "one" \relative c'' {
734 c4 b8. a16 g4. f8 e4 d c2
736 \new Lyrics \lyricsto "one" {
737 No more let sins and sor -- rows grow.
742 TODO: get some vocal person to write more.
745 @node TODO new sec fundamental
746 @section TODO new sec fundamental
752 * On the un-nestedness of brackets and ties::
755 @c my name start sucking the more docs I write. -gp
756 @node On the un-nestedness of brackets and ties
757 @subsection On the un-nestedness of brackets and ties
759 Different kinds of brackets and ties may be mixed freely,
761 TODO: improve this example
763 @lilypond[quote,verbatim,fragment,ragged-right]
765 r16[ g16 \times 2/3 {r16 e'8] }
766 g16( a \times 2/3 {b d e') }
767 g8[( a \times 2/3 {b d') e'~]}
768 \times 4/5 {e'32\( a b d' e'} a'4.\)
772 TODO... add more info? Fluff up the first sentence?
775 @node Extending the templates
776 @section Extending the templates
778 You've read the tutorial, you know how to write music. But how can you
779 get the staves that you want? The templates are ok, but what if you
780 want something that isn't covered?
783 * Soprano and cello::
784 * TODO another example of extending templates::
787 @node Soprano and cello
788 @subsection Soprano and cello
790 Start off with the template that seems closest to what you want to end
791 up with. Let's say that you want to write something for soprano and
792 cello. In this case, we would start with @q{Notes and lyrics} (for the
797 melody = \relative c' @{
811 \new Voice = "one" @{
815 \new Lyrics \lyricsto "one" \text
822 Now we want to add a cello part. Let's look at the @q{Notes only} example:
826 melody = \relative c' @{
841 We don't need two @code{\version} commands. We'll need the @code{melody}
842 section. We don't want two @code{\score} sections -- if we had two
843 @code{\score}s, we'd get the two parts separately. We want them together,
844 as a duet. Within the @code{\score} section, we don't need two
845 @code{\layout} or @code{\midi}.
847 If we simply cut and paste the @code{melody} section, we would end up with
848 two @code{melody} sections. So let's rename them. We'll call the section
849 for the soprano @code{sopranoMusic} and the section for the cello
850 @code{celloMusic}. While we're doing this, let's rename @code{text}
851 to be @code{sopranoLyrics}. Remember to rename both instances of all
852 these names -- both the initial definition (the
853 @code{melody = relative c' @{ } part) and the name's use (in the
854 @code{\score} section).
856 While we're doing this, let's change the cello part's staff -- celli
857 normally use bass clef. We'll also give the cello some different
862 sopranoMusic = \relative c' @{
870 sopranoLyrics = \lyricmode @{
874 celloMusic = \relative c @{
884 \new Voice = "one" @{
888 \new Lyrics \lyricsto "one" \sopranoLyrics
895 This is looking promising, but the cello part won't appear in the
896 score -- we haven't used it in the @code{\score} section. If we
897 want the cello part to appear under the soprano part, we need to add
900 \new Staff \celloMusic
904 underneath the soprano stuff. We also need to add @code{<<} and
905 @code{>>} around the music -- that tells LilyPond that there's
906 more than one thing (in this case, @code{Staff}) happening at once. The
907 @code{\score} looks like this now
913 \new Voice = "one" @{
917 \new Lyrics \lyricsto "one" \sopranoLyrics
919 \new Staff \celloMusic
927 This looks a bit messy; the indentation is messed up now. That is
928 easily fixed. Here's the complete soprano and cello template.
930 @lilypond[quote,verbatim,ragged-right]
932 sopranoMusic = \relative c' {
940 sopranoLyrics = \lyricmode {
944 celloMusic = \relative c {
959 \new Lyrics \lyricsto "one" \sopranoLyrics
961 \new Staff \celloMusic
969 @node TODO another example of extending templates
970 @subsection TODO another example of extending templates
972 TODO: somebody else fill this in. You guys like vocal stuff,
973 right? Get to it. :) -gp
977 @node Scores and parts
978 @section Scores and parts
980 TODO: this is really old stuff from the really old tutorial.
981 Rewrite, fix, etc. Or maybe delete entirely. -gp
983 In orchestral music, all notes are printed twice. Once in a part for
984 the musicians, and once in a full score for the conductor. Variables can
985 be used to avoid double work. The music is entered once, and stored in
986 a variable. The contents of that variable is then used to generate
987 both the part and the full score.
989 It is convenient to define the notes in a special file. For example,
990 suppose that the file @file{horn-music.ly} contains the following part
991 of a horn/@/bassoon duo
994 hornNotes = \relative c @{
1001 Then, an individual part is made by putting the following in a file
1004 \include "horn-music.ly"
1006 instrument = "Horn in F"
1010 \transpose f c' \hornNotes
1017 \include "horn-music.ly"
1021 substitutes the contents of @file{horn-music.ly} at this position in
1022 the file, so @code{hornNotes} is defined afterwards. The command
1023 @code{\transpose f@tie{}c'} indicates that the argument, being
1024 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
1025 @samp{f} is denoted by notated @code{c'}, which corresponds with the
1026 tuning of a normal French Horn in@tie{}F. The transposition can be seen
1027 in the following output
1029 @lilypond[quote,ragged-right]
1030 \transpose f c' \relative c {
1036 In ensemble pieces, one of the voices often does not play for many
1037 measures. This is denoted by a special rest, the multi-measure
1038 rest. It is entered with a capital @samp{R} followed by a duration
1039 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
1040 etc.). By multiplying the
1041 duration, longer rests can be constructed. For example, this rest
1042 takes 3@tie{}measures in 2/4 time
1048 When printing the part, multi-rests
1049 must be condensed. This is done by setting a run-time variable
1052 \set Score.skipBars = ##t
1056 This command sets the property @code{skipBars} in the
1057 @code{Score} context to true (@code{##t}). Prepending the rest and
1058 this option to the music above, leads to the following result
1060 @lilypond[quote,ragged-right]
1061 \transpose f c' \relative c {
1063 \set Score.skipBars = ##t
1070 The score is made by combining all of the music together. Assuming
1071 that the other voice is in @code{bassoonNotes} in the file
1072 @file{bassoon-music.ly}, a score is made with
1075 \include "bassoon-music.ly"
1076 \include "horn-music.ly"
1079 \new Staff \hornNotes
1080 \new Staff \bassoonNotes
1087 @lilypond[quote,ragged-right]
1095 r4 d,8 f | gis4 c | b bes |
1096 a8 e f4 | g d | gis f