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.
12 Tutorial Specification:
14 The LM is written in a tutorial style which introduces the most
15 important concepts, structure and syntax of the elements of a
16 LilyPond score in a carefully graded sequence of steps.
17 Explanations of all musical concepts used in the Manual can be
18 found in the Music Glossary, and readers are assumed to have no
19 prior knowledge of LilyPond. The objective is to take readers to
20 a level where the Notation Reference can be understood and
21 employed to both adapt the templates in the Appendix to their
22 needs and to begin to construct their own scores. Commonly used
23 tweaks are introduced and explained. Examples are provided
24 throughout which, while being focussed on the topic being
25 introduced, are long enough to seem real in order to retain the
26 readers' interest. Each example builds on the previous material,
27 and comments are used liberally. Every new aspect is thoroughly
28 explained before it is used.
33 Tutorial guidelines: (different from policy.txt!)
34 - unless you have a really good reason, use either
35 @lilypond[verbatim,quote,ragged-right]
37 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
39 Don't use any other relative=X commands (make it a non-fragment
40 example), and don't use fragment without relative=2.
42 - use "aes" and "ees" instead of "as" and "es". I know it's not
43 correct Dutch naming, but let's not confuse people with this
44 until we get to the Basic notation chapter.
46 - Add "Music Glossary: @rglos{foo}" to the _top_ of the relevant
47 portions of the tutorial.
55 This tutorial starts with an introduction to the LilyPond music
56 language and how to produce printed music. After this first
57 contact we will explain how to create common musical notation.
61 * Single staff notation::
62 * Multiple notes at once::
71 This section gives a basic introduction to working with LilyPond.
76 * Working on text files::
77 * How to read the tutorial::
81 @node Compiling a file
82 @subsection Compiling a file
84 The first example demonstrates how to start working with LilyPond.
85 To create sheet music, we write a text file that specifies the
86 notation. For example, if we write:
95 the result looks like this:
97 @c in this case we don't want verbatim
98 @lilypond[quote,ragged-right]
104 @warning{Every piece of LilyPond input needs to have
105 @strong{@{ curly braces @}} placed around the input. The braces
106 should also be surrounded by a space unless they are at the
107 beginning or end of a line to avoid ambiguities. The braces may
108 be omitted in some examples in this manual, but don't forget them
109 in your own music! For more information about the display of
110 examples in the manual, see @ref{How to read the tutorial}.}
112 @cindex case sensitive
113 In addition, LilyPond input is @strong{case sensitive}. @code{
114 @{ c d e @}} is valid input; @code{@{ C D E @}} will produce an
119 @subheading Entering music and viewing output
122 @cindex viewing music
124 In this section we will explain what commands to run and how to
125 view or print the output.
127 Note that there are several other text editors available with
128 better support for LilyPond. For more information, see
129 @rprogram{Text editor support}.
131 @warning{the first time you ever run LilyPond, it may take a
132 minute or two because all of the system fonts have to be analyzed
133 first. After this, LilyPond will be much faster!}
135 @subsubheading MacOS X
137 If you double click @code{LilyPond.app}, it will open with an
138 example file. Save it, for example, to @file{test.ly} on your
139 Desktop, and then process it with the menu command @code{Compile >
140 Typeset File}. The resulting PDF file will be displayed on your
143 For future use of LilyPond, you should begin by selecting @q{New}
144 or @q{Open}. You must save your file before typesetting it. If
145 any errors occur in processing, please see the log window.
148 @subsubheading Windows
150 On Windows, if you double-click in the LilyPond icon on the
151 Desktop, it will open a simple text editor with an example file.
152 Save it, for example, to @file{test.ly} on your Desktop and then
153 double-click on the file to process it (the file icon looks like a
154 note). After some seconds, you will get a file @file{test.pdf} on
155 your desktop. Double-click on this PDF file to view the typeset
156 score. An alternative method to process the @file{test.ly} file
157 is to drag and drop it onto the LilyPond icon using your mouse
160 To edit an existing @file{.ly} file, right-click on it and
161 select @qq{Edit source}. To get an empty file to start from, run
162 the editor as described above and use @qq{New} in
165 Double-clicking the file does not only result in a PDF file, but
166 also produces a @file{.log} file that contains some information on
167 what LilyPond has done to the file. If any errors occur, please
172 Create a file (such as @file{test.ly}) and enter:
180 To process @file{test.ly}, proceed as follows:
187 You will see something resembling:
194 Interpreting music...
195 Preprocessing graphical objects...
196 Finding the ideal number of pages...
197 Fitting music on 1 page...
199 Layout output to `test.ps'...
200 Converting to `test.pdf'...
204 @node Simple notation
205 @subsection Simple notation
207 LilyPond will add some notation elements automatically. In the
208 next example, we have only specified four pitches, but LilyPond
209 has added a clef, time signature, and rhythms.
211 @lilypond[verbatim,quote,ragged-right]
218 This behavior may be altered, but in most cases these automatic
224 Music Glossary: @rglos{pitch}, @rglos{interval},
225 @rglos{scale}, @rglos{middle C}, @rglos{octave},
228 The easiest way to enter notes is by using @code{\relative} mode.
229 In this mode, the octave is chosen automatically by assuming the
230 following note is always to be placed closest to the previous note,
231 i.e., it is to be placed in the octave which is within three
232 staff spaces of the previous note. We begin by entering the most
233 elementary piece of music, a @notation{scale}, in which every note
234 is within just one staff space of the previous note.
236 @lilypond[verbatim,quote,ragged-right]
237 \relative c' { % set the starting point to middle C
243 The initial note is @notation{middle C}. Each successive note is
244 placed closest to the previous note -- in other words, the first
245 @code{c} is the closest C to middle C. This is followed by the
246 closest D to the previous note. We can create melodies which
247 have larger intervals, still using only @code{\relative} mode:
249 @lilypond[verbatim,quote,ragged-right]
257 It is not necessary for the first note of the melody to start on
258 the note which specifies the starting pitch. In the previous
259 example, the first note -- the @code{d} -- is the closest D to
262 By adding (or removing) quotes @code{'} or commas @code{,} from
263 the @code{\relative c' @{} command, we can change the starting
266 @lilypond[verbatim,quote,ragged-right]
267 \relative c'' { % one octave above middle C
272 Relative mode can be confusing initially, but is the easiest way
273 to enter most melodies. Let us see how this relative calculation
274 works in practice. Starting from a B, which is on the middle line
275 in a treble clef, you can reach a C, D and E within 3 staff spaces
276 going up, and an A, G and F within 3 staff spaces going down. So
277 if the note following a B is a C, D or F it will be assumed to be
278 above the B, and an A, G or F will be assumed to be below.
280 @lilypond[verbatim,quote,ragged-right]
282 b c % c is 1 staff space up, so is the c above
283 b d % d is 2 up or 5 down, so is the d above
284 b e % e is 3 up or 4 down, so is the e above
285 b a % a is 4 up or 3 down, so is the a below
286 b g % g is 5 up or 2 down, so is the g below
287 b f % f is 6 up or 1 down, so is the f below
291 Exactly the same happens even when any of these notes are
292 sharpened or flattened. @notation{Accidentals} are @strong{totally
293 ignored} in the calculation of relative position. Precisely the
294 same staff space counting is done from a note at any other
295 position on the staff.
297 To add intervals that are larger than three staff spaces, we can
298 raise the @notation{octave} by adding a single quote @code{'} (or
299 apostrophe) to the note name. We can lower the octave by adding a
300 comma @code{,} to the note name.
302 @lilypond[verbatim,quote,ragged-right]
310 To change a note by two (or more!) octaves, we use multiple
311 @code{''} or @code{,,} -- but be careful that you use two single
312 quotes @code{''} and not one double quote @code{"}@tie{}! The
313 initial value in @code{\relative c'} may also be modified like
317 @subheading Durations (rhythms)
319 Music Glossary: @rglos{beam}, @rglos{duration}, @rglos{whole note},
320 @rglos{half note}, @rglos{quarter note}, @rglos{dotted note}.
322 The @notation{duration} of a note is specified by a number after
323 the note name. @code{1} for a @notation{whole note}, @code{2} for
324 a @notation{half note}, @code{4} for a @notation{quarter note} and
325 so on. @notation{Beams} are added automatically.
327 If you do not specify a duration, the previous duration is used
328 for the next note. The duration of the first note defaults to a
331 @lilypond[verbatim,quote,ragged-right]
335 a16 a a a a32 a a a a64 a a a a a a a a2
339 To create @notation{dotted notes}, add a dot @code{.} to the
340 duration number. The duration of a dotted note must be stated
341 explicitly (i.e., with a number).
343 @lilypond[verbatim,quote,ragged-right]
353 Music Glossary: @rglos{rest}.
355 A @notation{rest} is entered just like a note with the name @code{r}:
357 @lilypond[verbatim,quote,ragged-right]
365 @subheading Time signature
367 Music Glossary: @rglos{time signature}.
369 The @notation{time signature} can be set with the @code{\time}
372 @lilypond[verbatim,quote,ragged-right]
386 Music Glossary: @rglos{clef}.
388 The @notation{clef} can be set using the @code{\clef} command:
390 @lilypond[verbatim,quote,ragged-right]
404 @subheading All together
406 Here is a small example showing all these elements together:
408 @lilypond[verbatim,quote,ragged-right]
420 Notation Reference: @ruser{Writing pitches}, @ruser{Writing rhythms},
421 @ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}.
424 @c HERE's where I started
426 @node Working on text files
427 @subsection Working on text files
429 LilyPond input files are similar to source files in many common
430 programming languages. They are case sensitive, and white-space
431 is generally equivalent. Expressions are formed with curly braces
432 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
435 If the previous sentences sound like nonsense, don't worry! We'll
436 explain what all these terms mean:
440 @cindex case sensitive
442 @strong{Case sensitive}:
443 it matters whether you enter a letter in lower case (e.g. @code{a,
444 b, s, t}) or upper case (e.g. @code{A, B, S, T}). Notes are
445 lower case: @code{@{ c d e @}} is valid input; @code{@{ C D E @}}
446 will produce an error message.
449 @strong{Whitespace insensitive}:
450 it does not matter how many spaces (or new lines) you add.
451 @code{@{ c d e @}} means the same thing as @code{@{ c @tie{}
452 @tie{} @tie{} d e @}} and:
460 Of course, the previous example is hard to read. A good rule of
461 thumb is to indent code blocks with either a tab or two spaces:
470 @strong{Expressions}:
471 every piece of LilyPond input needs to have @strong{@{ curly
472 braces @}} placed around the input. These braces tell LilyPond
473 that the input is a single music expression, just like parentheses
474 @code{()} in mathematics. The braces should be surrounded by a
475 space unless they are at the beginning or end of a line to avoid
478 A function (such as @code{\relative @{ @}}) also counts as a
479 single music expression.
483 @cindex block comment
486 a comment is a remark for the human reader of the music input; it
487 is ignored while parsing, so it has no effect on the printed
488 output. There are two types of comments. The percent symbol
489 @code{%} introduces a line comment; anything after @code{%} on
490 that line is ignored. A block comment marks a whole section of
491 music input as a comment. Anything that is enclosed in @code{%@{}
492 and @code{%@}} is ignored. (Comments do not nest.) The following
493 fragment shows possible uses for comments:
496 % notes for twinkle twinkle follow
500 This line, and the notes below
501 are ignored, since they are in a
511 @node How to read the tutorial
512 @subsection How to read the tutorial
514 LilyPond input must be surrounded by @{ @} marks or a
515 @code{\relative c'' @{ ... @}}, as we saw in @ref{Working on text
516 files}. For the rest of this manual, most examples will omit
517 this. To replicate the examples, you may copy and paste the
518 displayed input but you @strong{must} add the @code{\relative c''
523 ... example goes here...
527 Why omit the braces? Most examples in this manual can be inserted
528 into the middle of a longer piece of music. For these examples,
529 it does not make sense to add @code{\relative c'' @{ @}} -- you
530 should not place a @code{\relative} inside another
531 @code{\relative}! If we included @code{\relative c'' @{ @}}
532 around every example, you would not be able to copy a small
533 documentation example and paste it inside a longer piece of your
534 own. Most people want to add material to an existing piece, so we
535 format the manual this way.
538 @subheading Clickable examples
540 Many people learn programs by trying and fiddling around with the
541 program. This is also possible with LilyPond. If you click on a
542 picture in the HTML version of this manual, you will see the exact
543 LilyPond input that was used to generate that image. Try it on
547 @lilypond[quote,ragged-right]
549 c-\markup { \bold \huge { Click here. } }
553 By cutting and pasting everything in the @qq{ly snippet} section,
554 you have a starting template for experiments. To see exactly the
555 same output (line-width and all), copy everything from @qq{Start
556 cut-&-pastable section} to the bottom of the file.
561 There are more tips for constructing input files in
562 @ref{Suggestions for writing LilyPond files}.
566 @node Single staff notation
567 @section Single staff notation
569 This section introduces common notation that is used for one voice
573 * Accidentals and key signatures::
575 * Articulation and dynamics::
577 * Automatic and manual beams::
578 * Advanced rhythmic commands::
582 @node Accidentals and key signatures
583 @subsection Accidentals and key signatures
585 @subheading Accidentals
587 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
588 @rglos{double flat}, @rglos{accidental}.
590 A @notation{sharp} pitch is made by adding @code{is} to the name, and
591 a @notation{flat} pitch by adding @code{es}. As you might expect, a
592 @notation{double sharp} or @notation{double flat} is made by adding
593 @code{isis} or @code{eses}. This syntax is derived from note
594 naming conventions in Nordic and Germanic languages, like German
595 and Dutch. To use other names for @notation{accidentals}, see
596 @ruser{Note names in other languages}.
598 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
599 cis1 ees fisis, aeses
602 @cindex key signature, setting
603 @subheading Key signatures
605 Music Glossary: @rglos{key signature}, @rglos{major}, @rglos{minor}.
607 The @notation{key signature} is set with the command @code{\key}
608 followed by a pitch and @code{\major} or @code{\minor}.
610 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
619 @subheading Warning: key signatures and pitches
621 Music Glossary: @rglos{accidental}, @rglos{key signature},
622 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
623 @rglos{transposition}.
625 To determine whether to print an @notation{accidental}, LilyPond
626 examines the pitches and the @notation{key signature}. The key
627 signature only affects the @emph{printed} accidentals, not the note's
628 @notation{pitch}! This is a feature that often causes confusion to
629 newcomers, so let us explain it in more detail.
631 LilyPond makes a sharp distinction between musical content and
632 layout. The alteration (@notation{flat}, @notation{natural} or
633 @notation{sharp}) of a note is part of the pitch, and is therefore
634 musical content. Whether an accidental (a @emph{printed} flat, natural
635 or sharp sign) is printed in front of the corresponding note is a
636 question of layout. Layout is something that follows rules, so
637 accidentals are printed automatically according to those rules. The
638 pitches in your music are works of art, so they will not be added
639 automatically, and you must enter what you want to hear.
643 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
649 No note has a printed accidental, but you must still add the
650 @code{is} to @code{cis} and @code{fis}.
652 The code @code{e} does not mean @qq{print a black dot just below
653 the first line of the staff.} Rather, it means @qq{there is a
654 note with pitch E-natural.} In the key of A-flat major, it
655 @emph{does} get an accidental:
657 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
662 Adding all alterations explicitly might require a little more
663 effort when typing, but the advantage is that
664 @notation{transposing} is easier, and accidentals can be printed
665 according to different conventions. For some examples how
666 accidentals can be printed according to different rules, see
667 @ruser{Automatic accidentals}.
671 Notation Reference: @ruser{Note names in other languages}, @ruser{Accidentals},
672 @ruser{Automatic accidentals}, @ruser{Key signature}.
674 Music Glossary: @rglos{Pitch names}.
678 @subsection Ties and slurs
683 Music Glossary: @rglos{tie}.
685 A @notation{tie} is created by appending a tilde @code{~} to the
686 first note being tied.
688 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
696 Music Glossary: @rglos{slur}.
698 A @notation{slur} is a curve drawn across many notes. The starting
699 note and ending note are marked with @code{(} and @code{)}
702 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
703 d4( c16) cis( d e c cis d) e( d4)
706 @cindex slurs, phrasing
707 @cindex phrasing slurs
708 @subheading Phrasing slurs
710 Music Glossary: @rglos{phrasing}, @rglos{legato}.
712 Slurs to indicate longer @notation{phrasing} can be entered with
713 @code{\(} and @code{\)}. You can have both @notation{legato} slurs and
714 phrasing slurs at the same time, but you cannot have simultaneous legato
715 slurs or simultaneous phrasing slurs.
717 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
718 a8(\( ais b c) cis2 b'2 a4 cis,\)
723 @cindex slurs versus ties
724 @subheading Warnings: slurs vs. ties
726 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
728 A @notation{slur} looks like a @notation{tie}, but it has a different
729 meaning. A tie simply makes the first note longer, and can only be
730 used on pairs of notes with the same pitch. Slurs indicate the
731 @notation{articulation} of notes, and can be used on larger groups of
732 notes. Slurs and ties can be nested.
734 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
735 c2~( c8 fis fis4 ~ fis2 g2)
740 Notation Reference: @ruser{Ties}, @ruser{Slurs},
741 @ruser{Phrasing slurs}.
744 @node Articulation and dynamics
745 @subsection Articulation and dynamics
750 @subheading Articulations
752 Music Glossary: @rglos{articulation}.
754 Common @notation{articulations} can be added to a note using a
755 dash @code{-} and a single character:
757 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
758 c-. c-- c-> c-^ c-+ c-_
762 @subheading Fingerings
764 Music Glossary: @rglos{fingering}.
767 Similarly, @notation{fingering} indications can be added to a note using
768 a dash (@code{-}) and the digit to be printed:
770 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
774 Articulations and fingerings are usually placed automatically, but
775 you can specify a direction by replacing the dash (@code{-}) with @code{^} (up) or @code{_}
776 (down). You can also use multiple articulations on the same note.
777 However, in most cases it is best to let LilyPond determine the
778 articulation directions.
780 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
781 c_-^1 d^. f^4_2-> e^-_+
786 Music Glossary: @rglos{dynamics}, @rglos{crescendo},
789 @notation{Dynamic} signs are made by adding the markings (with a
790 backslash) to the note:
792 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
800 @notation{Crescendi} and @notation{decrescendi} are started with
801 the commands @code{\<} and @code{\>}. An ending dynamic, for
802 example @code{\f}, will finish the (de)crescendo, or the command
803 @code{\!} can be used:
805 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
811 Notation Reference: @ruser{Articulations},
812 @ruser{Fingering instructions}, @ruser{Dynamics}.
816 @subsection Adding text
818 Text may be added to your scores:
820 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
824 Extra formatting may be added with the @code{\markup} command:
826 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
827 c1^\markup{ \bold espr}
829 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
836 Notation Reference: @ruser{Writing text}.
839 @node Automatic and manual beams
840 @subsection Automatic and manual beams
842 Music Glossary: @rglos{beam}.
844 @cindex beams, by hand
845 All @notation{beams} are drawn automatically:
847 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
848 a8 ais d ees r d c16 b a8
852 If you do not like the automatic beams, they may be overridden
853 manually. Mark the first note to be beamed with @code{[} and the
854 last one with @code{]}.
856 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
857 a8[ ais] d[ ees r d] a b
862 Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
865 @node Advanced rhythmic commands
866 @subsection Advanced rhythmic commands
870 @cindex partial measure
871 @subheading Partial measure
873 Music Glossary: @rglos{anacrusis}.
875 A pickup (or @notation{anacrusis}) is entered with the keyword
876 @code{\partial}. It is followed by a duration: @code{\partial 4}
877 is a quarter note pickup and @code{\partial 8} an eighth note.
879 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
888 Music Glossary: @rglos{note value}, @rglos{triplet}.
890 @notation{Tuplets} are made with the @code{\times} keyword. It
891 takes two arguments: a fraction and a piece of music. The
892 duration of the piece of music is multiplied by the fraction.
893 Triplets make notes occupy 2/3 of their notated duration, so a
894 @notation{triplet} has 2/3 as its fraction
896 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
897 \times 2/3 { f8 g a }
899 \times 2/3 { f,8 g16[ a g a] }
906 @subheading Grace notes
908 Music Glossary: @rglos{grace notes}, @rglos{acciacccatura}, @rglos{appoggiatura}.
910 @notation{Grace notes} are created with the @code{\grace} command,
911 although they can also be created by prefixing a music expression
912 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
914 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
915 c2 \grace { a32[ b] } c2
916 c2 \appoggiatura b16 c2
917 c2 \acciaccatura b16 c2
922 Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
926 @node Multiple notes at once
927 @section Multiple notes at once
929 This section introduces having more than one note at the same
930 time: multiple instruments, multiple staves for a single
931 instrument (i.e. piano), and chords.
933 Polyphony in music refers to having more than one voice occurring
934 in a piece of music. Polyphony in LilyPond refers to having more
935 than one voice on the same staff.
938 * Music expressions explained::
941 * Combining notes into chords::
942 * Single staff polyphony::
946 @node Music expressions explained
947 @subsection Music expressions explained
949 In LilyPond input files, music is represented by @emph{music
950 expressions}. A single note is a music expression:
952 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
956 Enclosing a note in braces creates a @emph{compound music
957 expression}. Here we have created a compound music expression
960 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
964 Putting a group of music expressions (e.g. notes) in braces means
965 that they are in sequence (i.e. each one follows the previous
966 one). The result is another music expression:
968 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
972 @subheading Simultaneous music expressions: multiple staves
974 Music Glossary: @rglos{polyphony}.
976 This technique is useful for @notation{polyphonic} music. To
977 enter music with more voices or more staves, we combine
978 expressions in parallel. To indicate that two voices should play
979 at the same time, simply enter a simultaneous combination of music
980 expressions. A @q{simultaneous} music expression is formed by
981 enclosing expressions inside @code{<<} and @code{>>}. In the
982 following example, three sequences (all containing two separate
983 notes) are combined simultaneously:
985 @lilypond[verbatim,quote,ragged-right]
995 Note that we have indented each level of the input with a
996 different amount of space. LilyPond does not care how much (or
997 little) space there is at the beginning of a line, but indenting
998 LilyPond code like this makes it much easier for humans to read.
1000 @warning{each note is relative to the previous note in
1001 the input, not relative to the @code{c''} in the initial
1002 @code{\\relative} command.}
1005 @subheading Simultaneous music expressions: single staff
1007 To determine the number of staves in a piece, LilyPond looks at
1008 the first expression. If it is a single note, there is one staff;
1009 if there is a simultaneous expression, there is more than one
1012 @lilypond[verbatim,quote,ragged-right]
1015 << { e f } { c <<b d>> } >>
1020 @cindex music expression
1021 @subheading Analogy: mathematical expressions
1023 This mechanism is similar to mathematical formulas: a big formula
1024 is created by composing small formulas. Such formulas are called
1025 expressions, and they can contain other music expressions, so you
1026 can make arbitrarily complex and large expressions. For example,
1035 ((1 + 2) * 3) / (4 * 5)
1038 This is a sequence of expressions, where each expression is
1039 contained in the next (larger) one. The simplest expressions are
1040 numbers, and larger ones are made by combining expressions with
1041 operators (like @code{+}, @code{*} and @code{/}) and parentheses.
1042 Like mathematical expressions, music expressions can be nested
1043 arbitrarily deep, which is necessary for complex music like
1047 @node Multiple staves
1048 @subsection Multiple staves
1050 LilyPond input files are constructed out of music expressions, as
1051 we saw in @ref{Music expressions explained}. If the score begins
1052 with simultaneous music expressions, LilyPond creates multiples
1053 staves. However, it is easier to see what happens if we create
1054 each staff explicitly.
1056 To print more than one staff, each piece of music that makes up a
1057 staff is marked by adding @code{\new Staff} before it. These
1058 @code{Staff} elements are then combined in parallel with @code{<<}
1061 @lilypond[verbatim,quote,ragged-right]
1064 \new Staff { \clef treble c }
1065 \new Staff { \clef bass c,, }
1070 The command @code{\new} introduces a @q{notation context.} A
1071 notation context is an environment in which musical events (like
1072 notes or @code{\clef} commands) are interpreted. For simple
1073 pieces, such notation contexts are created automatically. For
1074 more complex pieces, it is best to mark contexts explicitly.
1076 There are several types of contexts. @code{Score}, @code{Staff},
1077 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
1078 lyric texts and @code{ChordNames} prints chord names.
1080 In terms of syntax, prepending @code{\new} to a music expression
1081 creates a bigger music expression. In this way it resembles the
1082 minus sign in mathematics. The formula @math{(4+5)} is an
1083 expression, so @math{-(4+5)} is a bigger expression.
1085 Time signatures entered in one staff affect all other
1086 staves@footnote{This behavior may be changed if desired; for
1087 details, see @ruser{Polymetric notation}.}. On the other hand,
1088 the key signature of one staff does @emph{not} affect other
1091 @lilypond[verbatim,quote,ragged-right]
1094 \new Staff { \clef treble \key d \major \time 3/4 c }
1095 \new Staff { \clef bass c,, }
1104 @subsection Piano staves
1106 @cindex staff switch, manual
1107 @cindex cross staff voice, manual
1109 Music Glossary: @rglos{brace}.
1111 Piano music is typeset in two staves connected by a
1113 Printing such a staff is similar to the polyphonic example in
1114 @ref{Multiple staves}. However, now this entire expression is
1115 inserted inside a @code{PianoStaff}:
1124 Here is a small example:
1126 @lilypond[verbatim,quote,ragged-right]
1129 \new Staff { \time 2/4 c4 e g g, }
1130 \new Staff { \clef bass c,, c' e c }
1137 Notation Reference: @ruser{Piano music}.
1140 @node Combining notes into chords
1141 @subsection Combining notes into chords
1145 Music Glossary: @rglos{chord}.
1147 @notation{Chords} can be made by surrounding pitches with single
1148 angle brackets. Angle brackets are the symbols @code{<} and
1151 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1152 r4 <c e g>4 <c f a>2
1155 You can combine markings like beams and ties with chords. They
1156 must be placed outside the angle brackets.
1158 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1159 r4 <c e g>8[ <c f a>]~ <c f a>2
1162 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1163 r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
1167 @node Single staff polyphony
1168 @subsection Single staff polyphony
1171 @cindex multiple voices
1172 @cindex voices, more -- on a staff
1173 When different melodic lines are combined on a single staff they
1174 are printed as polyphonic voices; each voice has its own stems,
1175 slurs and beams, and the top voice has the stems up, while the
1176 bottom voice has them down.
1178 Entering such parts is done by entering each voice as a sequence
1179 (with @code{@{...@}}) and combining these simultaneously,
1180 separating the voices with @code{\\}
1182 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1189 For polyphonic music typesetting, spacer rests can also be
1190 convenient; these are rests that do not print. They are useful
1191 for filling up voices that temporarily do not play. Here is the
1192 same example with a spacer rest (@code{s}) instead of a normal
1195 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1203 Again, these expressions can be nested arbitrarily.
1205 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1213 { <c g>1 ~ <c g>4 } \\
1221 Notation Reference: @ruser{Simultaneous notes}.
1227 This section introduces vocal music and simple song sheets.
1230 * Setting simple songs::
1231 * Aligning lyrics to a melody::
1232 * Lyrics to multiple staves::
1236 @node Setting simple songs
1237 @subsection Setting simple songs
1242 Music Glossary: @rglos{lyrics}.
1244 Here is the start of the melody to a nursery
1245 rhyme, @qq{Girls and boys come out to play}:
1247 @lilypond[verbatim,quote,ragged-right]
1251 d4 b8 c4 a8 d4 b8 g4
1255 The @notation{lyrics} can be set to these notes, combining both
1256 with the @code{\addlyrics} keyword. Lyrics are entered by
1257 separating each syllable with a space.
1259 @lilypond[verbatim,quote,ragged-right]
1264 d4 b8 c4 a8 d4 b8 g4
1267 Girls and boys come out to play,
1272 Note the curly brackets delimiting both the music and the lyrics,
1273 and the angle brackets @code{<< ... >>} around the whole piece to
1274 show that the music and lyrics are to occur at the same time.
1276 @node Aligning lyrics to a melody
1277 @subsection Aligning lyrics to a melody
1279 Music Glossary: @rglos{melisma}, @rglos{extender line}.
1282 @cindex extender line
1286 The next line in the nursery rhyme is @q{The moon doth shine as
1287 bright as day}. Let's extend it:
1289 @lilypond[verbatim,quote,ragged-right]
1294 d4 b8 c4 a8 d4 b8 g4
1295 g8 a4 b8 c b a d4 b8 g4.
1298 Girls and boys come out to play,
1299 The moon doth shine as bright as day;
1304 We see the extra lyrics do not align properly with the notes. The
1305 word @q{shine} should be sung on two notes, not one. This is
1306 called a @notation{melisma}, a single syllable sung to more than one
1307 note. There are several ways to spread a syllable over multiple
1308 notes, the simplest being to add a slur across them (see @ref{Ties
1311 @lilypond[verbatim,quote,ragged-right]
1316 d4 b8 c4 a8 d4 b8 g4
1317 g8 a4 b8 c([ b)] a d4 b8 g4.
1320 Girls and boys come out to play,
1321 The moon doth shine as bright as day;
1326 Here we have also used manual beaming (the square brackets @code{[
1327 ]} ) to generate the beaming which is customarily used with lyrics
1328 (see @ref{Automatic and manual beams}).
1330 If a syllable extends over several notes or a single very long
1331 note an @notation{extender line} is usually drawn from the syllable
1332 extending under all the notes for that syllable. It is entered as
1333 two underscores @code{__}. Here is an example from the first
1334 three bars of Dido's Lament, from Purcell's Dido and Æneas:
1336 @lilypond[verbatim,quote,ragged-right]
1342 b c4.( bes8 a4. g8 fis4.) g8 fis1
1346 am laid __ in earth,
1351 None of the examples so far have involved words containing more
1352 than one syllable. Such words are usually split one syllable to a
1353 note, with hyphens between syllables. Such hyphens are entered as
1354 two dashes, resulting in a centered hyphen between the syllables.
1355 Here is an example showing this and everything we have learned so
1356 far about aligning lyrics to notes.
1358 @c no ragged-right here because otherwise the hyphens get lost,
1359 @c but the example is long enough to avoid looking strange.
1360 @lilypond[verbatim,quote]
1366 d4 g4 g a8( b) g4 g4
1370 A -- way in a __ man -- ger,
1371 no __ crib for a bed, __
1376 Some lyrics, especially those in Italian, require the opposite:
1377 setting more than one syllable to a single note. This is
1378 achieved by linking the syllables together with a single
1379 underscore @code{_} (with no spaces), or enclosing them in
1380 quotes. Here's an example from Rossini's Figaro, where
1381 @q{al} has to be sung on the same note as the @q{go} of
1382 @q{Largo} in Figaro's aria @q{Largo al factotum}:
1384 @c no ragged-right here because otherwise the hyphens get lost,
1385 @c but the example is long enough to avoid looking strange.
1386 @lilypond[verbatim,quote]
1392 c4.~ c8 d b c([ d)] b c d b c
1395 Lar -- go_al fac -- to -- tum del -- la cit -- tĂ
1403 Notation Reference: @ruser{Vocal music}.
1406 @node Lyrics to multiple staves
1407 @subsection Lyrics to multiple staves
1409 The simple approach using @code{\addlyrics} can be used for
1410 placing lyrics under more than one staff. Here is an
1411 example from Handel's Judas Maccabæus:
1413 @lilypond[verbatim,quote,ragged-right]
1421 c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
1424 Let flee -- cy flocks the hills a -- dorn, __
1428 r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
1431 Let flee -- cy flocks the hills a -- dorn,
1436 but scores any more complex than this simple example are
1437 better produced by separating out the staff structure
1438 from the notes and lyrics with variables. These are
1439 discussed later (see @ref{Organizing pieces with variables}).
1443 Notation Reference: @ruser{Vocal music}.
1447 @section Final touches
1449 This is the final section of the tutorial; it demonstrates how to
1450 add the final touches to simple pieces, and provides an
1451 introduction to the rest of the manual.
1456 * Absolute note names::
1457 * Organizing pieces with variables::
1458 * After the tutorial::
1459 * How to read the manual::
1463 @node Version number
1464 @subsection Version number
1467 The @code{\version} statement records the version of LilyPond that
1468 was used to write the file:
1475 By convention, this is placed at the top of your LilyPond file.
1477 These annotations make future upgrades of LilyPond go more
1478 smoothly. Changes in the syntax are handled with a special
1479 program, @file{convert-ly}, and it uses @code{\version} to
1480 determine what rules to apply. For details, see
1481 @rprogram{Updating files with convert-ly}.
1485 @subsection Adding titles
1487 The title, composer, opus number, and similar information are
1488 entered in the @code{\header} block. This exists outside of the
1489 main music expression; the @code{\header} block is usually placed
1490 underneath the @ref{Version number}.
1501 @dots{} music @dots{}
1505 When the file is processed, the title and composer are printed
1506 above the music. More information on titling can be found in
1507 @ruser{Creating titles}.
1510 @node Absolute note names
1511 @subsection Absolute note names
1513 So far we have always used @code{\relative} to define pitches.
1514 This is the easiest way to enter most music, but another way of
1515 defining pitches exists: absolute mode.
1517 If you omit the @code{\relative}, LilyPond treats all pitches as
1518 absolute values. A @code{c'} will always mean middle C, a
1519 @code{b} will always mean the note one step below middle C, and a
1520 @code{g,} will always mean the note on the bottom staff of the
1523 @lilypond[verbatim,quote,ragged-right]
1531 Here is a four-octave scale:
1533 @lilypond[verbatim,quote,ragged-right]
1548 As you can see, writing a melody in the treble clef involves a lot
1549 of quote @code{'} marks. Consider this fragment from Mozart:
1551 @lilypond[verbatim,quote,ragged-right]
1555 cis''8. d''16 cis''8 e''4 e''8
1556 b'8. cis''16 b'8 d''4 d''8
1560 All these quotes makes the input less readable and it is a source
1561 of errors. With @code{\relative}, the previous example is much
1564 @lilypond[verbatim,quote,ragged-right]
1568 cis8. d16 cis8 e4 e8
1573 If you make a mistake with an octave mark (@code{'} or @code{,})
1574 while working in @code{\relative} mode, it is very obvious -- many
1575 notes will be in the wrong octave. When working in absolute mode,
1576 a single mistake will not be as visible, and will not be as easy
1579 However, absolute mode is useful for music which has large
1580 intervals, and is extremely useful for computer-generated LilyPond
1584 @node Organizing pieces with variables
1585 @subsection Organizing pieces with variables
1587 When all of the elements discussed earlier are combined to produce
1588 larger files, the music expressions get a lot bigger. In
1589 polyphonic music with many staves, the input files can become very
1590 confusing. We can reduce this confusion by using
1593 With variables (also known as identifiers or macros), we can break
1594 up complex music expressions. A variable is assigned as
1598 namedMusic = @{ @dots{} @}
1601 The contents of the music expression @code{namedMusic} can be used
1602 later by placing a backslash in front of the name
1603 (@code{\namedMusic}, just like a normal LilyPond command).
1604 Variables must be defined @emph{before} the main music
1607 @lilypond[verbatim,quote,ragged-right]
1608 violin = \new Staff { \relative c'' {
1611 cello = \new Staff { \relative c {
1624 The name of a variable must have alphabetic characters only, no
1625 numbers, underscores, or dashes.
1627 It is possible to use variables for many other types of objects in
1628 the input. For example,
1633 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1636 Depending on its contents, the variable can be used in different
1637 places. The following example uses the above variables:
1648 @node After the tutorial
1649 @subsection After the tutorial
1651 After finishing the tutorial, you should probably try writing a
1652 piece or two. Start by adding notes to one of the @ref{Templates}.
1653 If you need any notation that was not covered in the
1654 tutorial, look at the Notation Reference, starting with
1655 @ruser{Musical notation}. If you want to write for an instrument
1656 ensemble that is not covered in the templates, take a look at
1657 @ref{Extending the templates}.
1659 Once you have written a few short pieces, read the rest of the
1660 Learning Manual (chapters 3-5). There's nothing wrong with
1661 reading it now, of course! However, the rest of the Learning
1662 Manual assumes that you are familiar with LilyPond input. You may
1663 wish to skim these chapters right now, and come back to them after
1664 you have more experience.
1667 @node How to read the manual
1668 @subsection How to read the manual
1670 Many examples in the tutorial omitted a @code{\relative c'' @{
1671 ... @}} around the printed example, as we saw in
1672 @ref{How to read the tutorial}.
1674 In the rest of the manual, we are much more lax about the printed
1675 examples: sometimes they may have omitted a @code{\relative c'' @{
1676 ... @}}, but other times a different initial pitch may be used
1677 (such as @code{c'} or @code{c,,}), and in some cases the whole
1678 example is in absolute note mode! However, ambiguities like this
1679 only exist where the pitches are not important. In any example
1680 where the pitch matters, we have explicitly stated
1681 @code{\relative} or absolute-mode @code{@{ @}}.
1683 If you are still confused about the exact LilyPond input that was
1684 used in an example, read the HTML version (if you are not already
1685 doing so) and click on the picture of the music. This will
1686 display the exact input that LilyPond used to generate this
1689 For information about the structure of the rest of the manual, see
1690 @ref{About this manual}.