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 @l ilypond[verbatim,quote,ragged-right]
15 @l ilypond[verbatim,quote,ragged-right,fragment,relative=2]
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.
30 This tutorial starts with an introduction to the LilyPond music
31 language and how to produce printed music. After this first
32 contact we will explain how to create common musical notation.
36 * Single staff notation::
37 * Multiple notes at once::
46 This section gives a basic introduction to working with LilyPond.
51 * Working on text files::
52 * How to read the tutorial::
56 @node Compiling a file
57 @subsection Compiling a file
59 The first example demonstrates how to start working with LilyPond.
60 To create sheet music, we write a text file that specifies the
61 notation. For example, if we write
70 the result looks like this
72 @c in this case we don't want verbatim
73 @lilypond[quote,ragged-right]
79 @warning{Every piece of LilyPond input needs to have
80 @strong{@{ curly braces @}} placed around the input. The braces
81 should also be surrounded by a space unless they are at the
82 beginning or end of a line to avoid ambiguities. The braces may
83 be omitted in some examples in this manual, but don't forget them
84 in your own music! For more information about the display of
85 examples in the manual, see @ref{How to read the tutorial}.}
87 @cindex Case sensitive
88 In addition, LilyPond input is @strong{case sensitive}. @code{
89 @{ c d e @}} is valid input; @code{@{ C D E @}} will produce an
94 @subheading Entering music and viewing output
99 In this section we will explain what commands to run and how to
100 view or print the output.
102 Note that there are several other text editors available with
103 better support for LilyPond. For more information, see
104 @rprogram{Text editor support}.
106 @warning{the first time you ever run LilyPond, it may take a
107 minute or two because all of the system fonts have to be analyzed
108 first. After this, LilyPond will be much faster!}
110 @subsubheading MacOS X
112 If you double click @code{LilyPond.app}, it will open with an
113 example file. Save it, for example, to @file{test.ly} on your
114 Desktop, and then process it with the menu command @samp{Compile >
115 Typeset File}. The resulting PDF file will be displayed on your
118 For future use of LilyPond, you should begin by selecting @q{New}
119 or @q{Open}. You must save your file before typesetting it. If
120 any errors occur in processing, please see the log window.
122 @subsubheading Windows
124 On Windows, if you double-click in the LilyPond icon on the
125 Desktop, it will open a simple text editor with an example file.
126 Save it, for example, to @file{test.ly} on your Desktop and then
127 double-click on the file to process it (the file icon looks like a
128 note). After some seconds, you will get a file @file{test.pdf} on
129 your desktop. Double-click on this PDF file to view the typeset
130 score. An alternative method to process the @file{test.ly} file
131 is to drag and drop it onto the LilyPond icon using your mouse
134 To edit an existing @file{.ly} file, right-click on it and
135 select @qq{Edit source}. To get an empty file to start from, run
136 the editor as described above and use @qq{New} in
139 Double-clicking the file does not only result in a PDF file, but
140 also produces a @file{.log} file that contains some information on
141 what LilyPond has done to the file. If any errors occur, please
146 Create a file (such as @file{test.ly}) and enter:
154 To process @file{test.ly}, proceed as follows
161 You will see something resembling
168 Interpreting music... [1]
169 Preprocessing graphical objects...
170 Calculating line breaks... [2]
171 Layout output to `test.ps'...
172 Converting to `test.pdf'...
176 @node Simple notation
177 @subsection Simple notation
179 LilyPond will add some notation elements automatically. In the
180 next example, we have only specified four pitches, but LilyPond
181 has added a clef, time signature, and rhythms.
183 @lilypond[verbatim,quote,ragged-right]
190 This behavior may be altered, but in most cases these automatic
196 Music glossary: @rglos{interval}, @rglos{fourth}, @rglos{scale},
199 The easiest way to enter notes is by using @code{\relative} mode.
200 In this mode, the @notation{interval} between the previous note and
201 the current note is assumed to be within a @notation{fourth}. We
202 begin by entering the most elementary piece of music, a
205 @lilypond[verbatim,quote,ragged-right]
212 The initial note is @notation{middle C}. Each successive note is
213 within a fourth of the previous note -- in other words, the first
214 @code{c} is the closest C to middle C. This is followed by the
215 closest D to the previous note. We can create melodies which have
218 @lilypond[verbatim,quote,ragged-right]
226 As you may notice, this example does not start on middle C. The
227 first note -- the @code{d} -- is the closest D to middle C.
229 To add intervals that are larger than a fourth, we can raise the
230 octave by adding a single quote @code{'} (or apostrophe) to the
231 note name. We can lower the octave by adding a comma @code{,} to
234 @lilypond[verbatim,quote,ragged-right]
242 To change a note by two (or more!) octaves, we use multiple
243 @code{''} or @code{,,} -- but be careful that you use two single
244 quotes @code{''} and not one double quote @code{"}@tie{}! The
245 initial value in @code{\relative c'} may also be modified like
249 @subheading Durations (rhythms)
251 Music glossary: @rglos{duration}, @rglos{whole note},
252 @rglos{half note}, @rglos{quarter note}, @rglos{dotted note}.
254 The @notation{duration} of a note is specified by a number after
255 the note name. @samp{1} for a @notation{whole note}, @samp{2} for
256 a @notation{half note}, @samp{4} for a @notation{quarter note} and
257 so on. Beams are added automatically.
259 @lilypond[verbatim,quote,ragged-right]
263 a16 a a a a32 a a a a64 a a a a a a a a2
268 If you do not specify a duration, the previous duration is used
269 for the next note. The duration of the first note defaults to a
272 To create @notation{dotted notes}, add a dot @samp{.} to the duration
275 @lilypond[verbatim,quote,ragged-right]
285 Music glossary: @rglos{rest}.
287 A @notation{rest} is entered just like a note with the name @samp{r}:
289 @lilypond[verbatim,quote,ragged-right]
297 @subheading Time signature
299 Music glossary: @rglos{time signature}.
301 The @notation{time signature}) can be set with the @code{\time}
304 @lilypond[verbatim,quote,ragged-right]
318 Music glossary: @rglos{clef}.
320 The @notation{clef} can be set using the @code{\clef} command:
322 @lilypond[verbatim,quote,ragged-right]
336 @subheading All together
338 Here is a small example showing all these elements together:
340 @lilypond[verbatim,quote,ragged-right]
352 User manual: @ruser{Writing pitches}, @ruser{Writing rhythms},
353 @ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}.
356 @c KURTIS: update stuff below this line with the style above.
358 @node Working on text files
359 @subsection Working on text files
361 LilyPond input files are similar to source files in many common
362 programming languages. They are case sensitive, and white-space
363 is generally equivalent. Expressions are formed with curly braces
364 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
367 If the previous sentence sounds like nonsense, don't worry! We'll
368 explain what all these terms mean:
372 @cindex Case sensitive
373 @item @strong{Case sensitive}:
374 it matters whether you enter a letter in lower case (i.e. @code{a,
375 b, s, t}) or upper case (i.e. @code{A, B, S, T}). Notes are
376 lower case: @code{@{ c d e @}} is valid input; @code{@{ C D E @}}
377 will produce an error message.
379 @item @strong{Whitespace insensitive}:
380 it does not matter how many spaces (or new lines) you add.
381 @code{@{ c d e @}} means the same thing as @code{@{ c @tie{}
382 @tie{} @tie{} d e @}} and
390 Of course, the previous example is hard to read. A good rule of
391 thumb is to indent code blocks with either a tab or two spaces:
399 @item @strong{Expressions:}
400 Every piece of LilyPond input needs to have @strong{@{ curly
401 braces @}} placed around the input. These braces tell LilyPond
402 that the input is a single music expression, just like parenthesis
403 @samp{()} in mathematics. The braces should be surrounded by a
404 space unless they are at the beginning or end of a line to avoid
407 A function (such as @code{\relative @{ @}}) also counts as a
408 single music expression.
412 @cindex block comment
413 @item @strong{Comments}:
414 A comment is a remark for the human reader of the music input; it
415 is ignored while parsing, so it has no effect on the printed
416 output. There are two types of comments. The percent symbol
417 @samp{%} introduces a line comment; anything after @samp{%} on
418 that line is ignored. A block comment marks a whole section of
419 music input as a comment. Anything that is enclosed in @code{%@{}
420 and @code{%@}} is ignored. (Comments do not nest.) The following
421 fragment shows possible uses for comments
424 % notes for twinkle twinkle follow
428 This line, and the notes below
429 are ignored, since they are in a
438 There are more tips for constructing input files in
439 @ruser{Suggestions for writing LilyPond files}.
442 @node How to read the tutorial
443 @subsection How to read the tutorial
445 As we saw in @ruser{Working on text files}, LilyPond input must be
446 surrounded by @{ @} marks or a @code{\relative c'' @{ ... @}}.
447 For the rest of this manual, most examples will omit this. To
448 replicate the examples, you may copy and paste the displayed input
449 but you @strong{must} add the @code{\relative c'' @{ @}} like
454 ... example goes here...
458 Why omit the braces? Most examples in this manual can be inserted
459 into the middle of a longer piece of music. For these examples,
460 it does not make sense to add @code{\relative c'' @{ @}} -- you
461 should not place a @code{\relative} inside another
462 @code{\relative}! If we included @code{\relative c'' @{ @}}
463 around every example, you would not be able to copy a small
464 documentation example and paste it inside a longer piece of your
465 own. Most people want to add material to an existing piece, so we
466 format the manual this way.
469 @subheading Clickable examples
471 Many people learn programs by trying and fiddling around with the
472 program. This is also possible with LilyPond. If you click on a
473 picture in the HTML version of this manual, you will see the exact
474 LilyPond input that was used to generate that image. Try it on
478 @lilypond[quote,ragged-right]
480 c-\markup { \bold \huge { Click here. } }
484 By cutting and pasting everything in the @qq{ly snippet} section,
485 you have a starting template for experiments. To see exactly the
486 same output (line-width and all), copy everything from @qq{Start
487 cut-&-pastable section} to the bottom of the file.
490 @node Single staff notation
491 @section Single staff notation
493 This section introduces common notation that is used for one voice
497 * Relative note names::
498 * Accidentals and key signatures::
500 * Articulation and dynamics::
501 * Automatic and manual beams::
502 * Advanced rhythmic commands::
506 @node Relative note names
507 @subsection Relative note names
509 As we saw in @ref{Simple notation}, LilyPond calculates the
510 pitch of each note relative to the previous one@footnote{There is
511 another mode of entering pitches, @ruser{Absolute note names}, but
512 in practice relative mode is much easier and safer to use.}. If
513 no extra octave marks (@code{'} and @code{,}) are added, it
514 assumes that each pitch is within a fourth of the previous note.
516 LilyPond examines pitches based on the note names -- in other
517 words, an augmented fourth is @emph{not} the same as a diminished
518 fifth. If we begin at a C, then an F-sharp will be placed a
519 higher than the C, while a G-flat will be placed lower than the C.
521 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
529 @item Relative octaves
530 see @ruser{Relative octaves}.
532 see @ruser{Octave check}.
538 @node Accidentals and key signatures
539 @subsection Accidentals and key signatures
541 @subheading Accidentals
543 A @rglos{sharp} pitch is made by adding @samp{is} to the name, and
544 a @rglos{flat} pitch by adding @samp{es}. As you might expect, a
545 @rglos{double sharp} or @rglos{double flat} is made by adding
546 @samp{isis} or @samp{eses}@footnote{This syntax derived from note
547 naming conventions in Nordic and Germanic languages, like German
548 and Dutch. To use other names for accidentals, see @ruser{Note
549 names in other languages}.}
551 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
552 cis1 ees fisis, aeses
555 @cindex key signature, setting
556 @subheading Key signatures
558 The key signature is set with the command @code{\key} followed by
559 a pitch and @code{\major} or @code{\minor}.
561 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
570 @subheading Warning: key signatures and pitches
572 To determine whether to print an accidental, LilyPond examines the
573 pitches and the key signature. The key signature only affects the
574 @emph{printed} accidentals, not the actual pitches! This is a
575 feature that often causes confusion to newcomers, so let us
576 explain it in more detail.
578 LilyPond makes a sharp distinction between musical content and
579 layout. The alteration (flat, natural or sharp) of a note is part
580 of the pitch, and is therefore musical content. Whether an
581 accidental (a @emph{printed} flat, natural or sharp sign) is
582 printed in front of the corresponding note is a question of
583 layout. Layout is something that follows rules, so accidentals
584 are printed automatically according to those rules. The pitches
585 in your music are works of art, so they will not be added
586 automatically, and you must enter what you want to hear.
590 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
596 No note has a printed accidental, but you must still add the
597 @samp{is} to @code{cis} and @code{fis}.
599 The code @samp{e} does not mean @qq{print a black dot just below
600 the first line of the staff.} Rather, it means: @qq{there is a
601 note with pitch E-natural.} In the key of A-flat major, it
602 @emph{does} get an accidental:
604 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
609 Adding all alterations explicitly might require a little more
610 effort when typing, but the advantage is that transposing is
611 easier, and accidentals can be printed according to different
612 conventions. See @ruser{Automatic accidentals}, for some examples
613 how accidentals can be printed according to different rules.
619 see @ruser{Accidentals}, and @ruser{Automatic accidentals}.
621 see @ruser{Key signature}.
627 @subsection Ties and slurs
631 A @rglos{tie} is created by appending a tilde @samp{~} to the
632 first note being tied
634 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
642 A @rglos{slur} is a curve drawn across many notes. The starting
643 note and ending note are marked with @samp{(} and @samp{)}
646 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
647 d4( c16) cis( d e c cis d) e( d4)
650 @cindex slurs, phrasing
651 @cindex phrasing slurs
652 @subheading Phrasing slurs
654 Slurs to indicate longer phrasing can be entered with @code{\(}
655 and @code{\)}. You can have both legato slurs and phrasing slurs
656 at the same time, but you cannot have simultaneous slurs or
657 simultaneous phrasing slurs.
659 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
660 a8(\( ais b c) cis2 b'2 a4 cis,\)
665 @cindex slurs versus ties
666 @subheading Warnings: slurs vs. ties
668 A slur looks like a @rglos{tie}, but it has a different meaning.
669 A tie simply makes the first note longer, and can only be used on
670 pairs of notes with the same pitch. Slurs indicate the
671 articulations of notes, and can be used on larger groups of notes.
672 Slurs and ties can be nested.
674 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
675 c2~( c8 fis fis4 ~ fis2 g2)
686 see @ruser{Phrasing slurs}.
691 @node Articulation and dynamics
692 @subsection Articulation and dynamics
697 @subheading Articulations
699 Common @rglos{articulation}s can be added to a note using a dash
700 @samp{-} and a single character:
702 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
703 c-. c-- c-> c-^ c-+ c-_
707 @subheading Fingerings
708 Similarly, fingering indications can be added to a note using a
709 dash (@samp{-}) and the digit to be printed:
711 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
715 Articulations and fingerings are usually placed automatically, but
716 you can specify a direction using @samp{^} (up) or @samp{_}
717 (down). You can also use multiple articulations on the same note.
718 However, in most cases it is best to let LilyPond determine the
719 articulation directions.
721 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
722 c_-^1 d^. f^4_2-> e^-_+
726 Dynamic signs are made by adding the markings (with a backslash)
729 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
737 Crescendi and decrescendi are started with the commands @code{\<}
738 and @code{\>}. An ending dynamic, for example @code{\f}, will
739 finish the (de)crescendo, or the command @code{\!} can be used
741 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
749 see @ruser{Articulations}.
751 see @ruser{Fingering instructions}.
753 see @ruser{Dynamics}.
758 @node Automatic and manual beams
759 @subsection Automatic and manual beams
761 @cindex beams, by hand
762 All @rglos{beam}s are drawn automatically:
764 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
765 a8 ais d ees r d c16 b a8
769 If you do not like the automatic beams, they may be overridden
770 manually. Mark the first note to be beamed with @samp{[} and the
771 last one with @samp{]}.
773 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
774 a8[ ais] d[ ees r d] a b
780 @item Automatic beams
781 see @ruser{Automatic beams}.
783 see @ruser{Manual beams}.
788 @node Advanced rhythmic commands
789 @subsection Advanced rhythmic commands
793 @cindex partial measure
794 @subheading Partial measure
796 A pickup (or @rglos{anacrusis}) is entered with the keyword
797 @code{\partial}. It is followed by a duration: @code{\partial 4}
798 is a quarter note pickup and @code{\partial 8} an eighth note.
800 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
809 Tuplets are made with the @code{\times} keyword. It takes two
810 arguments: a fraction and a piece of music. The duration of the
811 piece of music is multiplied by the fraction. Triplets make notes
812 occupy 2/3 of their notated duration, so a triplet has 2/3 as its
815 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
816 \times 2/3 { f8 g a }
818 \times 2/3 { f,8 g16[ a g a] }
825 @subheading Grace notes
827 Grace notes are created with the @code{\grace} command, although
828 they can also be created by prefixing a music expression with the
829 keyword @code{\appoggiatura} or @code{\acciaccatura}
831 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
832 c2 \grace { a32[ b] } c2
833 c2 \appoggiatura b16 c2
834 c2 \acciaccatura b16 c2
841 see @ruser{Grace notes},
845 see @ruser{Partial measures}.
850 @node Multiple notes at once
851 @section Multiple notes at once
853 This section introduces having more than one note at the same
854 time: multiple instruments, multiple staves for a single
855 instrument (i.e. piano), and chords.
857 Polyphony in music refers to having more than one voice occurring
858 in a piece of music. Polyphony in LilyPond refers to having more
859 than one voice on the same staff.
862 * Music expressions explained::
865 * Combining notes into chords::
866 * Single staff polyphony::
870 @node Music expressions explained
871 @subsection Music expressions explained
873 In LilyPond input files, music is represented by @emph{music
874 expressions}. A single note is a music expression:
876 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
880 Enclosing a note in braces creates a @emph{compound music
881 expression}. Here we have created a compound music expression
884 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
888 Putting a group of music expressions (e.g. notes) in braces means
889 that they are in sequence (i.e. each one follows the previous
890 one). The result is another music expression:
892 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
896 @subheading Simultaneous music expressions: multiple staves
898 This technique is useful for polyphonic music. To enter music
899 with more voices or more staves, we combine expressions in
900 parallel. To indicate that two voices should play at the same
901 time, simply enter a simultaneous combination of music
902 expressions. A @q{simultaneous} music expression is formed by
903 enclosing expressions inside @code{<<} and @code{>>}. In the
904 following example, three sequences (all containing two separate
905 notes) are combined simultaneously:
907 @lilypond[verbatim,quote,ragged-right]
917 Note that we have indented each level of the input with a
918 different amount of space. LilyPond does not care how much (or
919 little) space there is at the beginning of a line, but indenting
920 LilyPond code like this makes it much easier for humans to read.
922 @warning{each note is relative to the previous note in
923 the input, not relative to the @code{c''} in the initial
924 @code{\\relative} command.}
927 @subheading Simultaneous music expressions: single staff
929 To determine the number of staves in a piece, LilyPond looks at
930 the first expression. If it is a single note, there is one staff;
931 if there is a simultaneous expression, there is more than one
934 @lilypond[verbatim,quote,ragged-right]
937 << { e f } { c <<b d>> } >>
942 @cindex music expression
943 @subheading Analogy: mathematical expressions
945 This mechanism is similar to mathematical formulas: a big formula
946 is created by composing small formulas. Such formulas are called
947 expressions, and their definition is recursive so you can make
948 arbitrarily complex and large expressions. For example,
957 ((1 + 2) * 3) / (4 * 5)
960 This is a sequence of expressions, where each expression is
961 contained in the next (larger) one. The simplest expressions are
962 numbers, and larger ones are made by combining expressions with
963 operators (like @samp{+}, @samp{*} and @samp{/}) and parentheses.
964 Like mathematical expressions, music expressions can be nested
965 arbitrarily deep, which is necessary for complex music like
969 @node Multiple staves
970 @subsection Multiple staves
972 As we saw in @ruser{Music expressions explained}, LilyPond input
973 files are constructed out of music expressions. If the score
974 begins with simultaneous music expressions, LilyPond creates
975 multiples staves. However, it is easier to see what happens if we
976 create each staff explicitly.
978 To print more than one staff, each piece of music that makes up a
979 staff is marked by adding @code{\new Staff} before it. These
980 @code{Staff} elements are then combined in parallel with @code{<<}
983 @lilypond[verbatim,quote,ragged-right]
986 \new Staff { \clef treble c }
987 \new Staff { \clef bass c,, }
992 The command @code{\new} introduces a @q{notation context.} A
993 notation context is an environment in which musical events (like
994 notes or @code{\clef} commands) are interpreted. For simple
995 pieces, such notation contexts are created automatically. For
996 more complex pieces, it is best to mark contexts explicitly.
998 There are several types of contexts. @code{Score}, @code{Staff},
999 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
1000 lyric texts and @code{ChordNames} prints chord names.
1002 In terms of syntax, prepending @code{\new} to a music expression
1003 creates a bigger music expression. In this way it resembles the
1004 minus sign in mathematics. The formula @math{(4+5)} is an
1005 expression, so @math{-(4+5)} is a bigger expression.
1007 Time signatures entered in one staff affects all other
1008 staves@footnote{This behavior may be changed if desired; see
1009 @ruser{Polymetric notation}, for details.}. On the other hand, the
1010 key signature of one staff does @emph{not} affect other staves.
1012 @lilypond[verbatim,quote,ragged-right]
1015 \new Staff { \clef treble \time 3/4 c }
1016 \new Staff { \clef bass \key d \major c,, }
1025 @subsection Piano staves
1027 @cindex staff switch, manual
1028 @cindex cross staff voice, manual
1029 Piano music is typeset in two staves connected by a brace.
1030 Printing such a staff is similar to the polyphonic example in
1031 @ruser{Multiple staves}, but now this entire expression is
1032 inserted inside a @code{PianoStaff}:
1041 Here is a small example
1043 @lilypond[verbatim,quote,ragged-right]
1046 \new Staff { \time 2/4 c4 e g g, }
1047 \new Staff { \clef bass c,, c' e c }
1054 See @ruser{Piano music}.
1058 @node Combining notes into chords
1059 @subsection Combining notes into chords
1062 Chords can be made by surrounding pitches with single angle
1063 brackets. Angle brackets are the symbols @samp{<} and @samp{>}.
1065 @lilypond[quote,fragment,verbatim,relative=2,fragment]
1066 r4 <c e g>4 <c f a>2
1069 You can combine markings like beams and ties with chords. They
1070 must be placed outside the angle brackets
1072 @lilypond[quote,fragment,verbatim,relative=2,fragment]
1073 r4 <c e g>8[ <c f a>]~ <c f a>2
1076 @lilypond[quote,fragment,verbatim,relative=2,fragment]
1077 r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
1081 @node Single staff polyphony
1082 @subsection Single staff polyphony
1085 @cindex multiple voices
1086 @cindex voices, more -- on a staff
1087 When different melodic lines are combined on a single staff they
1088 are printed as polyphonic voices; each voice has its own stems,
1089 slurs and beams, and the top voice has the stems up, while the
1090 bottom voice has them down.
1092 Entering such parts is done by entering each voice as a sequence
1093 (with @code{@{...@}}) and combining these simultaneously,
1094 separating the voices with @code{\\}
1096 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1103 For polyphonic music typesetting, spacer rests can also be
1104 convenient; these are rests that do not print. They are useful
1105 for filling up voices that temporarily do not play. Here is the
1106 same example with a spacer rest (@samp{s}) instead of a normal
1109 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1117 Again, these expressions can be nested arbitrarily.
1119 @lilypond[quote,fragment,verbatim,relative=2,fragment]
1127 { <c g>1 ~ <c g>4 } \\
1135 See @ruser{Basic polyphony}.
1142 This section introduces vocal music and simple song sheets.
1145 * Setting simple songs::
1146 * Aligning lyrics to a melody::
1147 * Lyrics to multiple staves::
1151 @node Setting simple songs
1152 @subsection Setting simple songs
1156 Here is the start of the melody to a nursery
1157 rhyme, @qq{Girls and boys come out to play}:
1159 @lilypond[verbatim,quote,ragged-right]
1163 d4 b8 c4 a8 d4 b8 g4
1167 The lyrics can be set to these notes, combining both with the
1168 @code{\addlyrics} keyword. Lyrics are entered by separating each
1169 syllable with a space.
1171 @lilypond[verbatim,quote,ragged-right]
1176 d4 b8 c4 a8 d4 b8 g4
1179 Girls and boys come out to play,
1184 Note the curly brackets delimiting both the music and the lyrics,
1185 and the angle brackets @code{<< ... >>} around the whole piece to
1186 show that the music and lyrics are to occur at the same time.
1188 @node Aligning lyrics to a melody
1189 @subsection Aligning lyrics to a melody
1192 @cindex extender line
1196 The next line in the nursery rhyme is @q{The moon doth shine as
1197 bright as day}. Let's extend it:
1199 @lilypond[verbatim,quote,ragged-right]
1204 d4 b8 c4 a8 d4 b8 g4
1205 g8 a4 b8 c b a d4 b8 g4.
1208 Girls and boys come out to play,
1209 The moon doth shine as bright as day;
1214 We see the extra lyrics do not align properly with the notes. The
1215 word @q{shine} should be sung on two notes, not one. This is
1216 called a @rglos{melisma}, a single syllable sung to more than one
1217 note. There are several ways to spread a syllable over multiple
1218 notes, the simplest being to add a slur across them (see @ref{Ties
1221 @lilypond[verbatim,quote,ragged-right]
1226 d4 b8 c4 a8 d4 b8 g4
1227 g8 a4 b8 c([ b)] a d4 b8 g4.
1230 Girls and boys come out to play,
1231 The moon doth shine as bright as day;
1236 Here we have also used manual beaming (the square brackets @code{[
1237 ]} ) to generate the beaming which is customarily used with lyrics
1238 (see @ref{Automatic and manual beams}).
1240 If a syllable extends over several notes or a single very long
1241 note an @emph{extender line} is usually drawn from the syllable
1242 extending under all the notes for that syllable. It is entered as
1243 two underscores @code{__}. Here is an example from the first
1244 three bars of Dido's Lament, from Purcell's Dido and Æneas:
1246 @lilypond[verbatim,quote,ragged-right]
1252 b c4.( bes8 a4. g8 fis4.) g8 fis1
1256 am laid __ in earth,
1261 None of the examples so far have involved words containing more
1262 than one syllable. Such words are usually split one syllable to a
1263 note, with hyphens between syllables. Such hyphens are entered as
1264 two dashes, resulting in a centered hyphen between the syllables.
1265 Here is an example showing this and everything we have learned so
1266 far about aligning lyrics to notes.
1268 @c no ragged-right here because otherwise the hyphens get lost,
1269 @c but the example is long enough to avoid looking strange.
1270 @lilypond[quote,verbatim]
1276 d4 g4 g a8( b) g4 g4
1280 A -- way in a __ man -- ger,
1281 no __ crib for a bed, __
1286 Some lyrics, especially those in Italian, require the opposite:
1287 setting more than one syllable to a single note. This is
1288 achieved by linking the syllables together with a single
1289 underscore @code{_} (with no spaces), or enclosing them in
1290 quotes. Here's an example from Rossini's Figaro, where
1291 @q{al} has to be sung on the same note as the @q{go} of
1292 @q{Largo} in Figaro's aria @q{Largo al factotum}:
1294 @c no ragged-right here because otherwise the hyphens get lost,
1295 @c but the example is long enough to avoid looking strange.
1296 @lilypond[quote,verbatim]
1302 c4.~ c8 d b c([ d)] b c d b c
1305 Lar -- go_al fac -- to -- tum del -- la cit -- tĂ
1313 More options, such as inserting explicit rhythms into lyrics,
1314 inserting lyric ties (e.g., between @q{go al}) above,
1315 alternative ways of handling melismata,
1316 and adding extra verses,
1317 are discussed in @ruser{Vocal music}.
1320 @node Lyrics to multiple staves
1321 @subsection Lyrics to multiple staves
1323 The simple approach using @code{\addlyrics} can be used for
1324 placing lyrics under more than one staff. Here is an
1325 example from Handel's Judas Maccabæus:
1327 @lilypond[verbatim,quote,ragged-right]
1333 \relative c'' { \key f \major
1334 c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
1337 Let flee -- cy flocks the hills a -- dorn, __
1339 \relative c' { \key f \major
1340 r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
1343 Let flee -- cy flocks the hills a -- dorn,
1348 but scores any more complex than this simple example are
1349 better produced by separating out the staff structure
1350 from the notes and lyrics with variables. These are
1351 discussed later (see @ref{Organizing pieces with variables}).
1355 More options, such as putting multiple stanzas below the score,
1356 setting choral music, and lyrics to divided voices,
1357 are discussed in @ruser{Vocal music}.
1362 @section Final touches
1364 This is the final section of the tutorial; it demonstrates how to
1365 add the final touches to simple pieces, and provides an
1366 introduction to the rest of the manual.
1371 * Absolute note names::
1372 * Organizing pieces with variables::
1373 * After the tutorial::
1374 * How to read the manual::
1378 @node Version number
1379 @subsection Version number
1382 The @code{\version} statement records the version of LilyPond that
1383 was used to write the file:
1390 by convention, this is placed at the top of your LilyPond file.
1392 These annotations make future upgrades of LilyPond go more
1393 smoothly. Changes in the syntax are handled with a special
1394 program, @file{convert-ly} (see @rprogram{Updating files with
1395 convert-ly}), and it uses @code{\version} to determine what rules
1400 @subsection Adding titles
1402 The title, composer, opus number, and similar information are
1403 entered in the @code{\header} block. This exists outside of the
1404 main music expression; the @code{\header} block is usually placed
1405 underneath the @ruser{Version number}.
1416 @dots{} music @dots{}
1420 When the file is processed, the title and composer are printed
1421 above the music. More information on titling can be found in
1422 @ruser{Creating titles}.
1425 @node Absolute note names
1426 @subsection Absolute note names
1428 So far we have always used @code{\relative} to define pitches.
1429 This is the easiest way to enter most music, but another way of
1430 defining pitches exists: absolute mode.
1432 If you omit the @code{\relative}, LilyPond treats all pitches as
1433 absolute values. A @code{c'} will always mean middle C, a
1434 @code{b} will always mean the note one step below middle C, and a
1435 @code{g,} will always mean the note on the bottom staff of the
1438 @lilypond[quote,verbatim,ragged-right]
1446 Here is a four-octave scale:
1448 @lilypond[quote,verbatim,ragged-right]
1463 As you can see, writing a melody in the treble clef involves a lot
1464 of quote @code{'} marks. Consider this fragment from Mozart:
1466 @lilypond[quote,verbatim,ragged-right]
1470 cis''8. d''16 cis''8 e''4 e''8
1471 b'8. cis''16 b'8 d''4 d''8
1475 All these quotes makes the input less readable and it is a source
1476 of errors. With @code{\relative}, the previous example is much
1479 @lilypond[quote,verbatim,ragged-right]
1483 cis8. d16 cis8 e4 e8
1488 If you make a mistake with an octave mark (@code{'} or @code{,})
1489 while working in @code{\relative} mode, it is very obvious -- many
1490 notes will be in the wrong octave. When working in absolute mode,
1491 a single mistake will not be as visible, and will not be as easy
1494 However, absolute mode is useful for music which has large
1495 intervals, and is extremely useful for computer-generated LilyPond
1499 @node Organizing pieces with variables
1500 @subsection Organizing pieces with variables
1502 When all of the elements discussed earlier are combined to produce
1503 larger files, the music expressions get a lot bigger. In
1504 polyphonic music with many staves, the input files can become very
1505 confusing. We can reduce this confusion by using
1508 With variables (also known as variables or macros), we can break
1509 up complex music expressions. An variable is assigned as
1513 namedMusic = @{ @dots{} @}
1516 The contents of the music expression @code{namedMusic} can be used
1517 later by placing a backslash in front of the name
1518 (@code{\namedMusic}, just like a normal LilyPond command).
1519 Variables must be defined @emph{before} the main music
1522 @lilypond[quote,verbatim,ragged-right]
1523 violin = \new Staff { \relative c'' {
1526 cello = \new Staff { \relative c {
1539 The name of an variable must have alphabetic characters only: no
1540 numbers, underscores, or dashes.
1542 It is possible to use variables for many other types of objects in
1543 the input. For example,
1548 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1551 Depending on its contents, the variable can be used in different
1552 places. The following example uses the above variables:
1563 @node After the tutorial
1564 @subsection After the tutorial
1566 After finishing the tutorial, you should probably try writing a
1567 piece or two. Start with one of the @ruser{Templates}, and add
1568 notes. If you need any notation that was not covered in the
1569 tutorial, look at the Notation Reference, starting with
1570 @ruser{Basic notation}. If you want to write for an instrument
1571 ensemble that is not covered in the templates, take a look at
1572 @ruser{Extending the templates}.
1574 Once you have written a few short pieces, read the rest of the
1575 Learning Manual (chapters 3-5). There's nothing wrong with
1576 reading it now, of course! However, the rest of the Learning
1577 Manual assumes that you are familiar with LilyPond input. You may
1578 wish to skim these chapters right now, and come back to them after
1579 you have more experience.
1582 @node How to read the manual
1583 @subsection How to read the manual
1585 As we saw in @ruser{How to read the tutorial}, many examples in
1586 the tutorial omitted a @code{\relative c'' @{ ... @}} around the
1589 In the rest of the manual, we are much more lax about the printed
1590 examples: sometimes they may have omitted a @code{\relative c'' @{
1591 ... @}}, but other times a different initial pitch may be used
1592 (such as @code{c'} or @code{c,,}), and in some cases the whole
1593 example is in absolute note mode! However, ambiguities like this
1594 only exist where the pitches are not important. In any example
1595 where the pitch matters, we have explicitly stated
1596 @code{\relative} or absolute-mode @code{@{ @}}.
1598 If you are still confused about the exact LilyPond input that was
1599 used in an example, read the HTML version (if you are not already
1600 doing so) and click on the picture of the music. This will
1601 display the exact input that LilyPond used to generate this
1604 For information about the structure of the rest of the manual, see
1605 @ruser{About this manual}.