1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
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. See TRANSLATION for details.
11 Tutorial guidelines: (different from policy.txt!)
12 - unless you have a really good reason, use either
13 @lilypond[verbatim,quote,ragged-right]
15 blah @lilypond[verbatim,quote,ragged-right,fragment,relative=2] f
17 Don't use any other relative=X commands (make it a non-fragment
18 example), and don't use fragment without relative=2.
19 - use "aes" and "ees" instead of "as" and "aes". I know it's not
20 correct Dutch naming, but let's not confuse people with this
21 until we get to the Basic notation chapter.
22 - Add "Music glossary: @r gloss{foo}" to the _top_ of the relevant
23 portions of the tutorial.
34 This tutorial starts with an introduction to the LilyPond music
35 language and how to produce printed music. After this first
36 contact we will explain how to create common musical notation.
40 * Single staff notation::
41 * Multiple notes at once::
50 This section gives a basic introduction to working with LilyPond.
55 * Working on text files::
56 * How to read the tutorial::
60 @node Compiling a file
61 @subsection Compiling a file
63 The first example demonstrates how to start working with LilyPond.
64 To create sheet music, we write a text file that specifies the
65 notation. For example, if we write
74 the result looks like this
76 @c in this case we don't want verbatim
77 @lilypond[quote,ragged-right]
83 @warning{Every piece of LilyPond input needs to have
84 @strong{@{ curly braces @}} placed around the input. The braces
85 should also be surrounded by a space unless they are at the
86 beginning or end of a line to avoid ambiguities. The braces may
87 be omitted in some examples in this manual, but don't forget them
88 in your own music! For more information about the display of
89 examples in the manual, see @ref{How to read the tutorial}.}
91 @cindex Case sensitive
92 In addition, LilyPond input is @strong{case sensitive}. @code{
93 @{ c d e @}} is valid input; @code{@{ C D E @}} will produce an
98 @subheading Entering music and viewing output
101 @cindex Viewing music
103 In this section we will explain what commands to run and how to
104 view or print the output.
106 Note that there are several other text editors available with
107 better support for LilyPond. For more information, see
108 @rprogram{Text editor support}.
110 @warning{the first time you ever run LilyPond, it may take a
111 minute or two because all of the system fonts have to be analyzed
112 first. After this, LilyPond will be much faster!}
114 @subsubheading MacOS X
116 If you double click @code{LilyPond.app}, it will open with an
117 example file. Save it, for example, to @file{test.ly} on your
118 Desktop, and then process it with the menu command @samp{Compile >
119 Typeset File}. The resulting PDF file will be displayed on your
122 For future use of LilyPond, you should begin by selecting @q{New}
123 or @q{Open}. You must save your file before typesetting it. If
124 any errors occur in processing, please see the log window.
126 @subsubheading Windows
128 On Windows, if you double-click in the LilyPond icon on the
129 Desktop, it will open a simple text editor with an example file.
130 Save it, for example, to @file{test.ly} on your Desktop and then
131 double-click on the file to process it (the file icon looks like a
132 note). After some seconds, you will get a file @file{test.pdf} on
133 your desktop. Double-click on this PDF file to view the typeset
134 score. An alternative method to process the @file{test.ly} file
135 is to drag and drop it onto the LilyPond icon using your mouse
138 To edit an existing @file{.ly} file, right-click on it and
139 select @qq{Edit source}. To get an empty file to start from, run
140 the editor as described above and use @qq{New} in
143 Double-clicking the file does not only result in a PDF file, but
144 also produces a @file{.log} file that contains some information on
145 what LilyPond has done to the file. If any errors occur, please
150 Create a file (such as @file{test.ly}) and enter:
158 To process @file{test.ly}, proceed as follows
165 You will see something resembling
172 Interpreting music... [1]
173 Preprocessing graphical objects...
174 Calculating line breaks... [2]
175 Layout output to `test.ps'...
176 Converting to `test.pdf'...
180 @node Simple notation
181 @subsection Simple notation
183 LilyPond will add some notation elements automatically. In the
184 next example, we have only specified four pitches, but LilyPond
185 has added a clef, time signature, and rhythms.
187 @lilypond[verbatim,quote,ragged-right]
194 This behavior may be altered, but in most cases these automatic
200 Music glossary: @rglos{interval}, @rglos{fourth}, @rglos{scale},
203 The easiest way to enter notes is by using @code{\relative} mode.
204 In this mode, the @notation{interval} between the previous note and
205 the current note is assumed to be within a @notation{fourth}. We
206 begin by entering the most elementary piece of music, a
209 @lilypond[verbatim,quote,ragged-right]
216 The initial note is @notation{middle C}. Each successive note is
217 within a fourth of the previous note -- in other words, the first
218 @code{c} is the closest C to middle C. This is followed by the
219 closest D to the previous note. We can create melodies which have
222 @lilypond[verbatim,quote,ragged-right]
230 As you may notice, this example does not start on middle C. The
231 first note -- the @code{d} -- is the closest D to middle C.
233 To add intervals that are larger than a fourth, we can raise the
234 octave by adding a single quote @code{'} (or apostrophe) to the
235 note name. We can lower the octave by adding a comma @code{,} to
238 @lilypond[verbatim,quote,ragged-right]
246 To change a note by two (or more!) octaves, we use multiple
247 @code{''} or @code{,,} -- but be careful that you use two single
248 quotes @code{''} and not one double quote @code{"}@tie{}! The
249 initial value in @code{\relative c'} may also be modified like
253 @subheading Durations (rhythms)
255 Music glossary: @rglos{duration}, @rglos{whole note},
256 @rglos{half note}, @rglos{quarter note}, @rglos{dotted note}.
258 The @notation{duration} of a note is specified by a number after
259 the note name. @samp{1} for a @notation{whole note}, @samp{2} for
260 a @notation{half note}, @samp{4} for a @notation{quarter note} and
261 so on. Beams are added automatically.
263 @lilypond[verbatim,quote,ragged-right]
267 a16 a a a a32 a a a a64 a a a a a a a a2
272 If you do not specify a duration, the previous duration is used
273 for the next note. The duration of the first note defaults to a
276 To create @notation{dotted notes}, add a dot @samp{.} to the duration
279 @lilypond[verbatim,quote,ragged-right]
289 Music glossary: @rglos{rest}.
291 A @notation{rest} is entered just like a note with the name @samp{r}:
293 @lilypond[verbatim,quote,ragged-right]
301 @subheading Time signature
303 Music glossary: @rglos{time signature}.
305 The @notation{time signature}) can be set with the @code{\time}
308 @lilypond[verbatim,quote,ragged-right]
322 Music glossary: @rglos{clef}.
324 The @notation{clef} can be set using the @code{\clef} command:
326 @lilypond[verbatim,quote,ragged-right]
340 @subheading All together
342 Here is a small example showing all these elements together:
344 @lilypond[verbatim,quote,ragged-right]
356 User manual: @ruser{Writing pitches}, @ruser{Writing rhythms},
357 @ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}.
360 @c KURTIS: update stuff below this line with the style above.
362 @node Working on text files
363 @subsection Working on text files
365 LilyPond input files are similar to source files in many common
366 programming languages. They are case sensitive, and white-space
367 is generally equivalent. Expressions are formed with curly braces
368 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
371 If the previous sentence sounds like nonsense, don't worry! We'll
372 explain what all these terms mean:
376 @cindex Case sensitive
377 @item @strong{Case sensitive}:
378 it matters whether you enter a letter in lower case (i.e. @code{a,
379 b, s, t}) or upper case (i.e. @code{A, B, S, T}). Notes are
380 lower case: @code{@{ c d e @}} is valid input; @code{@{ C D E @}}
381 will produce an error message.
383 @item @strong{Whitespace insensitive}:
384 it does not matter how many spaces (or new lines) you add.
385 @code{@{ c d e @}} means the same thing as @code{@{ c @tie{}
386 @tie{} @tie{} d e @}} and
394 Of course, the previous example is hard to read. A good rule of
395 thumb is to indent code blocks with either a tab or two spaces:
403 @item @strong{Expressions:}
404 Every piece of LilyPond input needs to have @strong{@{ curly
405 braces @}} placed around the input. These braces tell LilyPond
406 that the input is a single music expression, just like parenthesis
407 @samp{()} in mathematics. The braces should be surrounded by a
408 space unless they are at the beginning or end of a line to avoid
411 A function (such as @code{\relative @{ @}}) also counts as a
412 single music expression.
416 @cindex block comment
417 @item @strong{Comments}:
418 A comment is a remark for the human reader of the music input; it
419 is ignored while parsing, so it has no effect on the printed
420 output. There are two types of comments. The percent symbol
421 @samp{%} introduces a line comment; anything after @samp{%} on
422 that line is ignored. A block comment marks a whole section of
423 music input as a comment. Anything that is enclosed in @code{%@{}
424 and @code{%@}} is ignored. (Comments do not nest.) The following
425 fragment shows possible uses for comments
428 % notes for twinkle twinkle follow
432 This line, and the notes below
433 are ignored, since they are in a
442 There are more tips for constructing input files in
443 @ruser{Suggestions for writing LilyPond files}.
446 @node How to read the tutorial
447 @subsection How to read the tutorial
449 As we saw in @ruser{Working on text files}, LilyPond input must be
450 surrounded by @{ @} marks or a @code{\relative c'' @{ ... @}}.
451 For the rest of this manual, most examples will omit this. To
452 replicate the examples, you may copy and paste the displayed input
453 but you @strong{must} add the @code{\relative c'' @{ @}} like
458 ... example goes here...
462 Why omit the braces? Most examples in this manual can be inserted
463 into the middle of a longer piece of music. For these examples,
464 it does not make sense to add @code{\relative c'' @{ @}} -- you
465 should not place a @code{\relative} inside another
466 @code{\relative}! If we included @code{\relative c'' @{ @}}
467 around every example, you would not be able to copy a small
468 documentation example and paste it inside a longer piece of your
469 own. Most people want to add material to an existing piece, so we
470 format the manual this way.
473 @subheading Clickable examples
475 Many people learn programs by trying and fiddling around with the
476 program. This is also possible with LilyPond. If you click on a
477 picture in the HTML version of this manual, you will see the exact
478 LilyPond input that was used to generate that image. Try it on
482 @lilypond[quote,ragged-right]
484 c-\markup { \bold \huge { Click here. } }
488 By cutting and pasting everything in the @qq{ly snippet} section,
489 you have a starting template for experiments. To see exactly the
490 same output (line-width and all), copy everything from @qq{Start
491 cut-&-pastable section} to the bottom of the file.
494 @node Single staff notation
495 @section Single staff notation
497 This section introduces common notation that is used for one voice
501 * Relative note names::
502 * Accidentals and key signatures::
504 * Articulation and dynamics::
505 * Automatic and manual beams::
506 * Advanced rhythmic commands::
510 @node Relative note names
511 @subsection Relative note names
513 As we saw in @ref{Simple notation}, LilyPond calculates the
514 pitch of each note relative to the previous one@footnote{There is
515 another mode of entering pitches, @ruser{Absolute note names}, but
516 in practice relative mode is much easier and safer to use.}. If
517 no extra octave marks (@code{'} and @code{,}) are added, it
518 assumes that each pitch is within a fourth of the previous note.
520 LilyPond examines pitches based on the note names -- in other
521 words, an augmented fourth is @emph{not} the same as a diminished
522 fifth. If we begin at a C, then an F-sharp will be placed a
523 higher than the C, while a G-flat will be placed lower than the C.
525 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
533 @item Relative octaves
534 see @ruser{Relative octaves}.
536 see @ruser{Octave check}.
542 @node Accidentals and key signatures
543 @subsection Accidentals and key signatures
545 @subheading Accidentals
547 A @rglos{sharp} pitch is made by adding @samp{is} to the name, and
548 a @rglos{flat} pitch by adding @samp{es}. As you might expect, a
549 @rglos{double sharp} or @rglos{double flat} is made by adding
550 @samp{isis} or @samp{eses}@footnote{This syntax derived from note
551 naming conventions in Nordic and Germanic languages, like German
552 and Dutch. To use other names for accidentals, see @ruser{Note
553 names in other languages}.}
555 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
556 cis1 ees fisis, aeses
559 @cindex key signature, setting
560 @subheading Key signatures
562 The key signature is set with the command @code{\key} followed by
563 a pitch and @code{\major} or @code{\minor}.
565 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
574 @subheading Warning: key signatures and pitches
576 To determine whether to print an accidental, LilyPond examines the
577 pitches and the key signature. The key signature only affects the
578 @emph{printed} accidentals, not the actual pitches! This is a
579 feature that often causes confusion to newcomers, so let us
580 explain it in more detail.
582 LilyPond makes a sharp distinction between musical content and
583 layout. The alteration (flat, natural or sharp) of a note is part
584 of the pitch, and is therefore musical content. Whether an
585 accidental (a @emph{printed} flat, natural or sharp sign) is
586 printed in front of the corresponding note is a question of
587 layout. Layout is something that follows rules, so accidentals
588 are printed automatically according to those rules. The pitches
589 in your music are works of art, so they will not be added
590 automatically, and you must enter what you want to hear.
594 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
600 No note has a printed accidental, but you must still add the
601 @samp{is} to @code{cis} and @code{fis}.
603 The code @samp{e} does not mean @qq{print a black dot just below
604 the first line of the staff.} Rather, it means: @qq{there is a
605 note with pitch E-natural.} In the key of A-flat major, it
606 @emph{does} get an accidental:
608 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
613 Adding all alterations explicitly might require a little more
614 effort when typing, but the advantage is that transposing is
615 easier, and accidentals can be printed according to different
616 conventions. See @ruser{Automatic accidentals}, for some examples
617 how accidentals can be printed according to different rules.
623 see @ruser{Accidentals}, and @ruser{Automatic accidentals}.
625 see @ruser{Key signature}.
631 @subsection Ties and slurs
635 A @rglos{tie} is created by appending a tilde @samp{~} to the
636 first note being tied
638 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
646 A @rglos{slur} is a curve drawn across many notes. The starting
647 note and ending note are marked with @samp{(} and @samp{)}
650 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
651 d4( c16) cis( d e c cis d) e( d4)
654 @cindex slurs, phrasing
655 @cindex phrasing slurs
656 @subheading Phrasing slurs
658 Slurs to indicate longer phrasing can be entered with @code{\(}
659 and @code{\)}. You can have both legato slurs and phrasing slurs
660 at the same time, but you cannot have simultaneous slurs or
661 simultaneous phrasing slurs.
663 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
664 a8(\( ais b c) cis2 b'2 a4 cis,\)
669 @cindex slurs versus ties
670 @subheading Warnings: slurs vs. ties
672 A slur looks like a @rglos{tie}, but it has a different meaning.
673 A tie simply makes the first note longer, and can only be used on
674 pairs of notes with the same pitch. Slurs indicate the
675 articulations of notes, and can be used on larger groups of notes.
676 Slurs and ties can be nested.
678 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
679 c2~( c8 fis fis4 ~ fis2 g2)
690 see @ruser{Phrasing slurs}.
695 @node Articulation and dynamics
696 @subsection Articulation and dynamics
701 @subheading Articulations
703 Common @rglos{articulation}s can be added to a note using a dash
704 @samp{-} and a single character:
706 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
707 c-. c-- c-> c-^ c-+ c-_
711 @subheading Fingerings
712 Similarly, fingering indications can be added to a note using a
713 dash (@samp{-}) and the digit to be printed:
715 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
719 Articulations and fingerings are usually placed automatically, but
720 you can specify a direction using @samp{^} (up) or @samp{_}
721 (down). You can also use multiple articulations on the same note.
722 However, in most cases it is best to let LilyPond determine the
723 articulation directions.
725 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
726 c_-^1 d^. f^4_2-> e^-_+
730 Dynamic signs are made by adding the markings (with a backslash)
733 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
741 Crescendi and decrescendi are started with the commands @code{\<}
742 and @code{\>}. An ending dynamic, for example @code{\f}, will
743 finish the (de)crescendo, or the command @code{\!} can be used
745 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
753 see @ruser{Articulations}.
755 see @ruser{Fingering instructions}.
757 see @ruser{Dynamics}.
762 @node Automatic and manual beams
763 @subsection Automatic and manual beams
765 @cindex beams, by hand
766 All @rglos{beam}s are drawn automatically:
768 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
769 a8 ais d ees r d c16 b a8
773 If you do not like the automatic beams, they may be overridden
774 manually. Mark the first note to be beamed with @samp{[} and the
775 last one with @samp{]}.
777 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
778 a8[ ais] d[ ees r d] a b
784 @item Automatic beams
785 see @ruser{Automatic beams}.
787 see @ruser{Manual beams}.
792 @node Advanced rhythmic commands
793 @subsection Advanced rhythmic commands
797 @cindex partial measure
798 @subheading Partial measure
800 A pickup (or @rglos{anacrusis}) is entered with the keyword
801 @code{\partial}. It is followed by a duration: @code{\partial 4}
802 is a quarter note pickup and @code{\partial 8} an eighth note.
804 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
813 Tuplets are made with the @code{\times} keyword. It takes two
814 arguments: a fraction and a piece of music. The duration of the
815 piece of music is multiplied by the fraction. Triplets make notes
816 occupy 2/3 of their notated duration, so a triplet has 2/3 as its
819 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
820 \times 2/3 { f8 g a }
822 \times 2/3 { f,8 g16[ a g a] }
829 @subheading Grace notes
831 Grace notes are created with the @code{\grace} command, although
832 they can also be created by prefixing a music expression with the
833 keyword @code{\appoggiatura} or @code{\acciaccatura}
835 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
836 c2 \grace { a32[ b] } c2
837 c2 \appoggiatura b16 c2
838 c2 \acciaccatura b16 c2
845 see @ruser{Grace notes},
849 see @ruser{Partial measures}.
854 @node Multiple notes at once
855 @section Multiple notes at once
857 This section introduces having more than one note at the same
858 time: multiple instruments, multiple staves for a single
859 instrument (i.e. piano), and chords.
861 Polyphony in music refers to having more than one voice occurring
862 in a piece of music. Polyphony in LilyPond refers to having more
863 than one voice on the same staff.
866 * Music expressions explained::
869 * Combining notes into chords::
870 * Single staff polyphony::
874 @node Music expressions explained
875 @subsection Music expressions explained
877 In LilyPond input files, music is represented by @emph{music
878 expressions}. A single note is a music expression:
880 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
884 Enclosing a note in braces creates a @emph{compound music
885 expression}. Here we have created a compound music expression
888 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
892 Putting a group of music expressions (e.g. notes) in braces means
893 that they are in sequence (i.e. each one follows the previous
894 one). The result is another music expression:
896 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
900 @subheading Simultaneous music expressions: multiple staves
902 This technique is useful for polyphonic music. To enter music
903 with more voices or more staves, we combine expressions in
904 parallel. To indicate that two voices should play at the same
905 time, simply enter a simultaneous combination of music
906 expressions. A @q{simultaneous} music expression is formed by
907 enclosing expressions inside @code{<<} and @code{>>}. In the
908 following example, three sequences (all containing two separate
909 notes) are combined simultaneously:
911 @lilypond[verbatim,quote,ragged-right]
921 Note that we have indented each level of the input with a
922 different amount of space. LilyPond does not care how much (or
923 little) space there is at the beginning of a line, but indenting
924 LilyPond code like this makes it much easier for humans to read.
926 @warning{each note is relative to the previous note in
927 the input, not relative to the @code{c''} in the initial
928 @code{\\relative} command.}
931 @subheading Simultaneous music expressions: single staff
933 To determine the number of staves in a piece, LilyPond looks at
934 the first expression. If it is a single note, there is one staff;
935 if there is a simultaneous expression, there is more than one
938 @lilypond[verbatim,quote,ragged-right]
941 << { e f } { c <<b d>> } >>
946 @cindex music expression
947 @subheading Analogy: mathematical expressions
949 This mechanism is similar to mathematical formulas: a big formula
950 is created by composing small formulas. Such formulas are called
951 expressions, and their definition is recursive so you can make
952 arbitrarily complex and large expressions. For example,
961 ((1 + 2) * 3) / (4 * 5)
964 This is a sequence of expressions, where each expression is
965 contained in the next (larger) one. The simplest expressions are
966 numbers, and larger ones are made by combining expressions with
967 operators (like @samp{+}, @samp{*} and @samp{/}) and parentheses.
968 Like mathematical expressions, music expressions can be nested
969 arbitrarily deep, which is necessary for complex music like
973 @node Multiple staves
974 @subsection Multiple staves
976 As we saw in @ruser{Music expressions explained}, LilyPond input
977 files are constructed out of music expressions. If the score
978 begins with simultaneous music expressions, LilyPond creates
979 multiples staves. However, it is easier to see what happens if we
980 create each staff explicitly.
982 To print more than one staff, each piece of music that makes up a
983 staff is marked by adding @code{\new Staff} before it. These
984 @code{Staff} elements are then combined in parallel with @code{<<}
987 @lilypond[verbatim,quote,ragged-right]
990 \new Staff { \clef treble c }
991 \new Staff { \clef bass c,, }
996 The command @code{\new} introduces a @q{notation context.} A
997 notation context is an environment in which musical events (like
998 notes or @code{\clef} commands) are interpreted. For simple
999 pieces, such notation contexts are created automatically. For
1000 more complex pieces, it is best to mark contexts explicitly.
1002 There are several types of contexts. @code{Score}, @code{Staff},
1003 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
1004 lyric texts and @code{ChordNames} prints chord names.
1006 In terms of syntax, prepending @code{\new} to a music expression
1007 creates a bigger music expression. In this way it resembles the
1008 minus sign in mathematics. The formula @math{(4+5)} is an
1009 expression, so @math{-(4+5)} is a bigger expression.
1011 Time signatures entered in one staff affects all other
1012 staves@footnote{This behavior may be changed if desired; see
1013 @ruser{Polymetric notation}, for details.}. On the other hand, the
1014 key signature of one staff does @emph{not} affect other staves.
1016 @lilypond[verbatim,quote,ragged-right]
1019 \new Staff { \clef treble \time 3/4 c }
1020 \new Staff { \clef bass \key d \major c,, }
1029 @subsection Piano staves
1031 @cindex staff switch, manual
1032 @cindex cross staff voice, manual
1033 Piano music is typeset in two staves connected by a brace.
1034 Printing such a staff is similar to the polyphonic example in
1035 @ruser{Multiple staves}, but now this entire expression is
1036 inserted inside a @code{PianoStaff}:
1045 Here is a small example
1047 @lilypond[verbatim,quote,ragged-right]
1050 \new Staff { \time 2/4 c4 e g g, }
1051 \new Staff { \clef bass c,, c' e c }
1058 See @ruser{Piano music}.
1062 @node Combining notes into chords
1063 @subsection Combining notes into chords
1066 Chords can be made by surrounding pitches with single angle
1067 brackets. Angle brackets are the symbols @samp{<} and @samp{>}.
1069 @lilypond[quote,fragment,verbatim,relative=2,fragment]
1070 r4 <c e g>4 <c f a>2
1073 You can combine markings like beams and ties with chords. They
1074 must be placed outside the angle brackets
1076 @lilypond[quote,fragment,verbatim,relative=2,fragment]
1077 r4 <c e g>8[ <c f a>]~ <c f a>2
1080 @lilypond[quote,fragment,verbatim,relative=2,fragment]
1081 r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
1085 @node Single staff polyphony
1086 @subsection Single staff polyphony
1089 @cindex multiple voices
1090 @cindex voices, more -- on a staff
1091 When different melodic lines are combined on a single staff they
1092 are printed as polyphonic voices; each voice has its own stems,
1093 slurs and beams, and the top voice has the stems up, while the
1094 bottom voice has them down.
1096 Entering such parts is done by entering each voice as a sequence
1097 (with @code{@{...@}}) and combining these simultaneously,
1098 separating the voices with @code{\\}
1100 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1107 For polyphonic music typesetting, spacer rests can also be
1108 convenient; these are rests that do not print. They are useful
1109 for filling up voices that temporarily do not play. Here is the
1110 same example with a spacer rest (@samp{s}) instead of a normal
1113 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1121 Again, these expressions can be nested arbitrarily.
1123 @lilypond[quote,fragment,verbatim,relative=2,fragment]
1131 { <c g>1 ~ <c g>4 } \\
1139 See @ruser{Basic polyphony}.
1146 This section introduces vocal music and simple song sheets.
1149 * Setting simple songs::
1150 * Aligning lyrics to a melody::
1151 * Lyrics to multiple staves::
1155 @node Setting simple songs
1156 @subsection Setting simple songs
1160 Here is the start of the melody to a nursery
1161 rhyme, @qq{Girls and boys come out to play}:
1163 @lilypond[verbatim,quote,ragged-right]
1167 d4 b8 c4 a8 d4 b8 g4
1171 The lyrics can be set to these notes, combining both with the
1172 @code{\addlyrics} keyword. Lyrics are entered by separating each
1173 syllable with a space.
1175 @lilypond[verbatim,quote,ragged-right]
1180 d4 b8 c4 a8 d4 b8 g4
1183 Girls and boys come out to play,
1188 Note the curly brackets delimiting both the music and the lyrics,
1189 and the angle brackets @code{<< ... >>} around the whole piece to
1190 show that the music and lyrics are to occur at the same time.
1192 @node Aligning lyrics to a melody
1193 @subsection Aligning lyrics to a melody
1196 @cindex extender line
1200 The next line in the nursery rhyme is @q{The moon doth shine as
1201 bright as day}. Let's extend it:
1203 @lilypond[verbatim,quote,ragged-right]
1208 d4 b8 c4 a8 d4 b8 g4
1209 g8 a4 b8 c b a d4 b8 g4.
1212 Girls and boys come out to play,
1213 The moon doth shine as bright as day;
1218 We see the extra lyrics do not align properly with the notes. The
1219 word @q{shine} should be sung on two notes, not one. This is
1220 called a @rglos{melisma}, a single syllable sung to more than one
1221 note. There are several ways to spread a syllable over multiple
1222 notes, the simplest being to add a slur across them (see @ref{Ties
1225 @lilypond[verbatim,quote,ragged-right]
1230 d4 b8 c4 a8 d4 b8 g4
1231 g8 a4 b8 c([ b)] a d4 b8 g4.
1234 Girls and boys come out to play,
1235 The moon doth shine as bright as day;
1240 Here we have also used manual beaming (the square brackets @code{[
1241 ]} ) to generate the beaming which is customarily used with lyrics
1242 (see @ref{Automatic and manual beams}).
1244 If a syllable extends over several notes or a single very long
1245 note an @emph{extender line} is usually drawn from the syllable
1246 extending under all the notes for that syllable. It is entered as
1247 two underscores @code{__}. Here is an example from the first
1248 three bars of Dido's Lament, from Purcell's Dido and Æneas:
1250 @lilypond[verbatim,quote,ragged-right]
1256 b c4.( bes8 a4. g8 fis4.) g8 fis1
1260 am laid __ in earth,
1265 None of the examples so far have involved words containing more
1266 than one syllable. Such words are usually split one syllable to a
1267 note, with hyphens between syllables. Such hyphens are entered as
1268 two dashes, resulting in a centered hyphen between the syllables.
1269 Here is an example showing this and everything we have learned so
1270 far about aligning lyrics to notes.
1272 @c no ragged-right here because otherwise the hyphens get lost,
1273 @c but the example is long enough to avoid looking strange.
1274 @lilypond[quote,verbatim]
1280 d4 g4 g a8( b) g4 g4
1284 A -- way in a __ man -- ger,
1285 no __ crib for a bed, __
1290 Some lyrics, especially those in Italian, require the opposite:
1291 setting more than one syllable to a single note. This is
1292 achieved by linking the syllables together with a single
1293 underscore @code{_} (with no spaces), or enclosing them in
1294 quotes. Here's an example from Rossini's Figaro, where
1295 @q{al} has to be sung on the same note as the @q{go} of
1296 @q{Largo} in Figaro's aria @q{Largo al factotum}:
1298 @c no ragged-right here because otherwise the hyphens get lost,
1299 @c but the example is long enough to avoid looking strange.
1300 @lilypond[quote,verbatim]
1306 c4.~ c8 d b c([ d)] b c d b c
1309 Lar -- go_al fac -- to -- tum del -- la cit -- tĂ
1317 More options, such as inserting explicit rhythms into lyrics,
1318 inserting lyric ties (e.g., between @q{go al}) above,
1319 alternative ways of handling melismata,
1320 and adding extra verses,
1321 are discussed in @ruser{Vocal music}.
1324 @node Lyrics to multiple staves
1325 @subsection Lyrics to multiple staves
1327 The simple approach using @code{\addlyrics} can be used for
1328 placing lyrics under more than one staff. Here is an
1329 example from Handel's Judas Maccabæus:
1331 @lilypond[verbatim,quote,ragged-right]
1337 \relative c'' { \key f \major
1338 c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
1341 Let flee -- cy flocks the hills a -- dorn, __
1343 \relative c' { \key f \major
1344 r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
1347 Let flee -- cy flocks the hills a -- dorn,
1352 but scores any more complex than this simple example are
1353 better produced by separating out the staff structure
1354 from the notes and lyrics with variables. These are
1355 discussed later (see @ref{Organizing pieces with variables}).
1359 More options, such as putting multiple stanzas below the score,
1360 setting choral music, and lyrics to divided voices,
1361 are discussed in @ruser{Vocal music}.
1366 @section Final touches
1368 This is the final section of the tutorial; it demonstrates how to
1369 add the final touches to simple pieces, and provides an
1370 introduction to the rest of the manual.
1375 * Absolute note names::
1376 * Organizing pieces with variables::
1377 * After the tutorial::
1378 * How to read the manual::
1382 @node Version number
1383 @subsection Version number
1386 The @code{\version} statement records the version of LilyPond that
1387 was used to write the file:
1394 by convention, this is placed at the top of your LilyPond file.
1396 These annotations make future upgrades of LilyPond go more
1397 smoothly. Changes in the syntax are handled with a special
1398 program, @file{convert-ly} (see @rprogram{Updating files with
1399 convert-ly}), and it uses @code{\version} to determine what rules
1404 @subsection Adding titles
1406 The title, composer, opus number, and similar information are
1407 entered in the @code{\header} block. This exists outside of the
1408 main music expression; the @code{\header} block is usually placed
1409 underneath the @ruser{Version number}.
1420 @dots{} music @dots{}
1424 When the file is processed, the title and composer are printed
1425 above the music. More information on titling can be found in
1426 @ruser{Creating titles}.
1429 @node Absolute note names
1430 @subsection Absolute note names
1432 So far we have always used @code{\relative} to define pitches.
1433 This is the easiest way to enter most music, but another way of
1434 defining pitches exists: absolute mode.
1436 If you omit the @code{\relative}, LilyPond treats all pitches as
1437 absolute values. A @code{c'} will always mean middle C, a
1438 @code{b} will always mean the note one step below middle C, and a
1439 @code{g,} will always mean the note on the bottom staff of the
1442 @lilypond[quote,verbatim,ragged-right]
1450 Here is a four-octave scale:
1452 @lilypond[quote,verbatim,ragged-right]
1467 As you can see, writing a melody in the treble clef involves a lot
1468 of quote @code{'} marks. Consider this fragment from Mozart:
1470 @lilypond[quote,verbatim,ragged-right]
1474 cis''8. d''16 cis''8 e''4 e''8
1475 b'8. cis''16 b'8 d''4 d''8
1479 All these quotes makes the input less readable and it is a source
1480 of errors. With @code{\relative}, the previous example is much
1483 @lilypond[quote,verbatim,ragged-right]
1487 cis8. d16 cis8 e4 e8
1492 If you make a mistake with an octave mark (@code{'} or @code{,})
1493 while working in @code{\relative} mode, it is very obvious -- many
1494 notes will be in the wrong octave. When working in absolute mode,
1495 a single mistake will not be as visible, and will not be as easy
1498 However, absolute mode is useful for music which has large
1499 intervals, and is extremely useful for computer-generated LilyPond
1503 @node Organizing pieces with variables
1504 @subsection Organizing pieces with variables
1506 When all of the elements discussed earlier are combined to produce
1507 larger files, the music expressions get a lot bigger. In
1508 polyphonic music with many staves, the input files can become very
1509 confusing. We can reduce this confusion by using
1512 With variables (also known as variables or macros), we can break
1513 up complex music expressions. An variable is assigned as
1517 namedMusic = @{ @dots{} @}
1520 The contents of the music expression @code{namedMusic} can be used
1521 later by placing a backslash in front of the name
1522 (@code{\namedMusic}, just like a normal LilyPond command).
1523 Variables must be defined @emph{before} the main music
1526 @lilypond[quote,verbatim,ragged-right]
1527 violin = \new Staff { \relative c'' {
1530 cello = \new Staff { \relative c {
1543 The name of an variable must have alphabetic characters only: no
1544 numbers, underscores, or dashes.
1546 It is possible to use variables for many other types of objects in
1547 the input. For example,
1552 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1555 Depending on its contents, the variable can be used in different
1556 places. The following example uses the above variables:
1567 @node After the tutorial
1568 @subsection After the tutorial
1570 After finishing the tutorial, you should probably try writing a
1571 piece or two. Start with one of the @ruser{Templates}, and add
1572 notes. If you need any notation that was not covered in the
1573 tutorial, look at the Notation Reference, starting with
1574 @ruser{Basic notation}. If you want to write for an instrument
1575 ensemble that is not covered in the templates, take a look at
1576 @ruser{Extending the templates}.
1578 Once you have written a few short pieces, read the rest of the
1579 Learning Manual (chapters 3-5). There's nothing wrong with
1580 reading it now, of course! However, the rest of the Learning
1581 Manual assumes that you are familiar with LilyPond input. You may
1582 wish to skim these chapters right now, and come back to them after
1583 you have more experience.
1586 @node How to read the manual
1587 @subsection How to read the manual
1589 As we saw in @ruser{How to read the tutorial}, many examples in
1590 the tutorial omitted a @code{\relative c'' @{ ... @}} around the
1593 In the rest of the manual, we are much more lax about the printed
1594 examples: sometimes they may have omitted a @code{\relative c'' @{
1595 ... @}}, but other times a different initial pitch may be used
1596 (such as @code{c'} or @code{c,,}), and in some cases the whole
1597 example is in absolute note mode! However, ambiguities like this
1598 only exist where the pitches are not important. In any example
1599 where the pitch matters, we have explicitly stated
1600 @code{\relative} or absolute-mode @code{@{ @}}.
1602 If you are still confused about the exact LilyPond input that was
1603 used in an example, read the HTML version (if you are not already
1604 doing so) and click on the picture of the music. This will
1605 display the exact input that LilyPond used to generate this
1608 For information about the structure of the rest of the manual, see
1609 @ruser{About this manual}.