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
15 most important concepts, structure and syntax of the
16 elements of a LilyPond score in a carefully graded sequence
17 of steps. Explanations of all musical concepts used in the
18 Manual can be found in the Music Glossary, and readers are
19 assumed to have no prior knowledge of LilyPond. The
20 objective is to take readers to a level where the Notation
21 Reference can be understood and employed to both adapt the
22 templates in the Appendix to their needs and to begin to
23 construct their own. Commonly used tweaks are introduced
24 and explained. Examples are provided throughout which,
25 while being focussed on the topic being introduced, are long
26 enough to seem real in order to retain the readers'
27 interest. Each example builds on the previous material, and
28 comments are used liberally. Every new aspect is thoroughly
29 explained before it is used.
34 Tutorial guidelines: (different from policy.txt!)
35 - unless you have a really good reason, use either
36 @lilypond[verbatim,quote,ragged-right]
38 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
40 Don't use any other relative=X commands (make it a non-fragment
41 example), and don't use fragment without relative=2.
43 - use "aes" and "ees" instead of "as" and "es". I know it's not
44 correct Dutch naming, but let's not confuse people with this
45 until we get to the Basic notation chapter.
47 - Add "Music glossary: @rglos{foo}" to the _top_ of the relevant
48 portions of the tutorial.
56 This tutorial starts with an introduction to the LilyPond music
57 language and how to produce printed music. After this first
58 contact we will explain how to create common musical notation.
62 * Single staff notation::
63 * Multiple notes at once::
72 This section gives a basic introduction to working with LilyPond.
77 * Working on text files::
78 * How to read the tutorial::
82 @node Compiling a file
83 @subsection Compiling a file
85 The first example demonstrates how to start working with LilyPond.
86 To create sheet music, we write a text file that specifies the
87 notation. For example, if we write:
96 the result looks like this:
98 @c in this case we don't want verbatim
99 @lilypond[quote,ragged-right]
105 @warning{Every piece of LilyPond input needs to have
106 @strong{@{ curly braces @}} placed around the input. The braces
107 should also be surrounded by a space unless they are at the
108 beginning or end of a line to avoid ambiguities. The braces may
109 be omitted in some examples in this manual, but don't forget them
110 in your own music! For more information about the display of
111 examples in the manual, see @ref{How to read the tutorial}.}
113 @cindex case sensitive
114 In addition, LilyPond input is @strong{case sensitive}. @code{
115 @{ c d e @}} is valid input; @code{@{ C D E @}} will produce an
120 @subheading Entering music and viewing output
123 @cindex viewing music
125 In this section we will explain what commands to run and how to
126 view or print the output.
128 Note that there are several other text editors available with
129 better support for LilyPond. For more information, see
130 @rprogram{Text editor support}.
132 @warning{the first time you ever run LilyPond, it may take a
133 minute or two because all of the system fonts have to be analyzed
134 first. After this, LilyPond will be much faster!}
136 @subsubheading MacOS X
138 If you double click @code{LilyPond.app}, it will open with an
139 example file. Save it, for example, to @file{test.ly} on your
140 Desktop, and then process it with the menu command @samp{Compile >
141 Typeset File}. The resulting PDF file will be displayed on your
144 For future use of LilyPond, you should begin by selecting @q{New}
145 or @q{Open}. You must save your file before typesetting it. If
146 any errors occur in processing, please see the log window.
149 @subsubheading Windows
151 On Windows, if you double-click in the LilyPond icon on the
152 Desktop, it will open a simple text editor with an example file.
153 Save it, for example, to @file{test.ly} on your Desktop and then
154 double-click on the file to process it (the file icon looks like a
155 note). After some seconds, you will get a file @file{test.pdf} on
156 your desktop. Double-click on this PDF file to view the typeset
157 score. An alternative method to process the @file{test.ly} file
158 is to drag and drop it onto the LilyPond icon using your mouse
161 To edit an existing @file{.ly} file, right-click on it and
162 select @qq{Edit source}. To get an empty file to start from, run
163 the editor as described above and use @qq{New} in
166 Double-clicking the file does not only result in a PDF file, but
167 also produces a @file{.log} file that contains some information on
168 what LilyPond has done to the file. If any errors occur, please
173 Create a file (such as @file{test.ly}) and enter:
181 To process @file{test.ly}, proceed as follows:
188 You will see something resembling:
195 Interpreting music...
196 Preprocessing graphical objects...
197 Finding the ideal number of pages...
198 Fitting music on 1 page...
200 Layout output to `test.ps'...
201 Converting to `test.pdf'...
205 @node Simple notation
206 @subsection Simple notation
208 LilyPond will add some notation elements automatically. In the
209 next example, we have only specified four pitches, but LilyPond
210 has added a clef, time signature, and rhythms.
212 @lilypond[verbatim,quote,ragged-right]
219 This behavior may be altered, but in most cases these automatic
225 Music glossary: @rglos{pitch}, @rglos{interval},
226 @rglos{scale}, @rglos{middle C}, @rglos{octave},
229 The easiest way to enter notes is by using @code{\relative} mode.
230 In this mode, the octave is chosen automatically by assuming the
231 following note is always to be placed closest to the previous note,
232 i.e., it is to be placed in the octave which is within three
233 staff spaces of the previous note. We begin by entering the most
234 elementary piece of music, a @notation{scale}, in which every note
235 is within just one staff space of the previous note.
237 @lilypond[verbatim,quote,ragged-right]
238 \relative c' { % set the starting point to middle C
244 The initial note is @notation{middle C}. Each successive note is
245 placed closest to the previous note -- in other words, the first
246 @code{c} is the closest C to middle C. This is followed by the
247 closest D to the previous note. We can create melodies which
248 have larger intervals:
250 @lilypond[verbatim,quote,ragged-right]
258 It is not necessary for the first note of the melody to start on
259 the note which specifies the starting pitch. In the previous
260 example, the first note -- the @code{d} -- is the closest D to
263 By adding (or removing) quotes @code{'} or commas @code{,} from
264 the @code{\relative c' @{} command, we can change the starting
267 @lilypond[verbatim,quote,ragged-right]
268 \relative c'' { % one octave above middle C
273 Relative mode can be confusing initially, but is the easiest way
274 to enter most melodies. Let us see how this relative calculation
275 works in practice. Starting from a B, which is on the middle line
276 in a treble clef, you can reach a C, D and E within 3 staff spaces
277 going up, and an A, G and F within 3 staff spaces going down. So
278 if the note following a B is a C, D or F it will be assumed to be
279 above the B, and an A, G or F will be assumed to be below.
281 @lilypond[verbatim,quote,ragged-right]
283 b c % c is 1 staff space up, so is the c above
284 b d % d is 2 up or 5 down, so is the d above
285 b e % e is 3 up or 4 down, so is the e above
286 b a % a is 4 up or 3 down, so is the a below
287 b g % g is 5 up or 2 down, so is the g below
288 b f % f is 6 up or 1 down, so is the f below
292 Exactly the same happens even when any of these notes are
293 sharpened or flatted. @notation{Accidentals} are @strong{totally
294 ignored} in the calculation of relative position. Precisely the
295 same staff space counting is done from a note at any other
296 position on the staff.
298 To add intervals that are larger than three staff spaces, we can
299 raise the @notation{octave} by adding a single quote @code{'} (or
300 apostrophe) to the note name. We can lower the octave by adding a
301 comma @code{,} to the note name.
303 @lilypond[verbatim,quote,ragged-right]
311 To change a note by two (or more!) octaves, we use multiple
312 @code{''} or @code{,,} -- but be careful that you use two single
313 quotes @code{''} and not one double quote @code{"}@tie{}! The
314 initial value in @code{\relative c'} may also be modified like
318 @subheading Durations (rhythms)
320 Music glossary: @rglos{beam}, @rglos{duration}, @rglos{whole note},
321 @rglos{half note}, @rglos{quarter note}, @rglos{dotted note}.
323 The @notation{duration} of a note is specified by a number after
324 the note name. @samp{1} for a @notation{whole note}, @samp{2} for
325 a @notation{half note}, @samp{4} for a @notation{quarter note} and
326 so on. @notation{Beams} are added automatically.
328 @lilypond[verbatim,quote,ragged-right]
332 a16 a a a a32 a a a a64 a a a a a a a a2
337 If you do not specify a duration, the previous duration is used
338 for the next note. The duration of the first note defaults to a
341 To create @notation{dotted notes}, add a dot @samp{.} to the duration
344 @lilypond[verbatim,quote,ragged-right]
354 Music glossary: @rglos{rest}.
356 A @notation{rest} is entered just like a note with the name @samp{r}:
358 @lilypond[verbatim,quote,ragged-right]
366 @subheading Time signature
368 Music glossary: @rglos{time signature}.
370 The @notation{time signature} can be set with the @code{\time}
373 @lilypond[verbatim,quote,ragged-right]
387 Music glossary: @rglos{clef}.
389 The @notation{clef} can be set using the @code{\clef} command:
391 @lilypond[verbatim,quote,ragged-right]
405 @subheading All together
407 Here is a small example showing all these elements together:
409 @lilypond[verbatim,quote,ragged-right]
421 Notation reference: @ruser{Writing pitches}, @ruser{Writing rhythms},
422 @ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}.
425 @c HERE's where I started
427 @node Working on text files
428 @subsection Working on text files
430 LilyPond input files are similar to source files in many common
431 programming languages. They are case sensitive, and white-space
432 is generally equivalent. Expressions are formed with curly braces
433 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
436 If the previous sentences sound like nonsense, don't worry! We'll
437 explain what all these terms mean:
441 @cindex case sensitive
443 @strong{Case sensitive}:
444 it matters whether you enter a letter in lower case (e.g. @code{a,
445 b, s, t}) or upper case (e.g. @code{A, B, S, T}). Notes are
446 lower case: @code{@{ c d e @}} is valid input; @code{@{ C D E @}}
447 will produce an error message.
450 @strong{Whitespace insensitive}:
451 it does not matter how many spaces (or new lines) you add.
452 @code{@{ c d e @}} means the same thing as @code{@{ c @tie{}
453 @tie{} @tie{} d e @}} and:
461 Of course, the previous example is hard to read. A good rule of
462 thumb is to indent code blocks with either a tab or two spaces:
471 @strong{Expressions:}
472 Every piece of LilyPond input needs to have @strong{@{ curly
473 braces @}} placed around the input. These braces tell LilyPond
474 that the input is a single music expression, just like parentheses
475 @samp{()} in mathematics. The braces should be surrounded by a
476 space unless they are at the beginning or end of a line to avoid
479 A function (such as @code{\relative @{ @}}) also counts as a
480 single music expression.
484 @cindex block comment
487 A comment is a remark for the human reader of the music input; it
488 is ignored while parsing, so it has no effect on the printed
489 output. There are two types of comments. The percent symbol
490 @samp{%} introduces a line comment; anything after @samp{%} on
491 that line is ignored. A block comment marks a whole section of
492 music input as a comment. Anything that is enclosed in @code{%@{}
493 and @code{%@}} is ignored. (Comments do not nest.) The following
494 fragment shows possible uses for comments:
497 % notes for twinkle twinkle follow
501 This line, and the notes below
502 are ignored, since they are in a
511 There are more tips for constructing input files in
512 @ref{Suggestions for writing LilyPond files}.
515 @node How to read the tutorial
516 @subsection How to read the tutorial
518 LilyPond input must be surrounded by @{ @} marks or a
519 @code{\relative c'' @{ ... @}}, as we saw in @ref{Working on text
520 files}. For the rest of this manual, most examples will omit
521 this. To replicate the examples, you may copy and paste the
522 displayed input but you @strong{must} add the @code{\relative c''
527 ... example goes here...
531 Why omit the braces? Most examples in this manual can be inserted
532 into the middle of a longer piece of music. For these examples,
533 it does not make sense to add @code{\relative c'' @{ @}} -- you
534 should not place a @code{\relative} inside another
535 @code{\relative}! If we included @code{\relative c'' @{ @}}
536 around every example, you would not be able to copy a small
537 documentation example and paste it inside a longer piece of your
538 own. Most people want to add material to an existing piece, so we
539 format the manual this way.
542 @subheading Clickable examples
544 Many people learn programs by trying and fiddling around with the
545 program. This is also possible with LilyPond. If you click on a
546 picture in the HTML version of this manual, you will see the exact
547 LilyPond input that was used to generate that image. Try it on
551 @lilypond[quote,ragged-right]
553 c-\markup { \bold \huge { Click here. } }
557 By cutting and pasting everything in the @qq{ly snippet} section,
558 you have a starting template for experiments. To see exactly the
559 same output (line-width and all), copy everything from @qq{Start
560 cut-&-pastable section} to the bottom of the file.
563 @node Single staff notation
564 @section Single staff notation
566 This section introduces common notation that is used for one voice
570 * Accidentals and key signatures::
572 * Articulation and dynamics::
574 * Automatic and manual beams::
575 * Advanced rhythmic commands::
579 @node Accidentals and key signatures
580 @subsection Accidentals and key signatures
582 @subheading Accidentals
584 Music glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
585 @rglos{double flat}, @rglos{accidental}.
587 A @notation{sharp} pitch is made by adding @samp{is} to the name, and
588 a @notation{flat} pitch by adding @samp{es}. As you might expect, a
589 @notation{double sharp} or @notation{double flat} is made by adding
590 @samp{isis} or @samp{eses}. This syntax derived from note
591 naming conventions in Nordic and Germanic languages, like German
592 and Dutch. To use other names for @notation{accidentals}, see
593 @ruser{Note names in other languages}.
595 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
596 cis1 ees fisis, aeses
599 @cindex key signature, setting
600 @subheading Key signatures
602 Music glossary: @rglos{key signature}, @rglos{major}, @rglos{minor}.
604 The @notation{key signature} is set with the command @code{\key}
605 followed by a pitch and @code{\major} or @code{\minor}.
607 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
616 @subheading Warning: key signatures and pitches
618 Music glossary: @rglos{accidental}, @rglos{key signature},
619 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
620 @rglos{transposition}.
622 To determine whether to print an @notation{accidental}, LilyPond
623 examines the pitches and the @notation{key signature}. The key
624 signature only affects the @emph{printed} accidentals, not the note's
625 @notation{pitch}! This is a feature that often causes confusion to
626 newcomers, so let us explain it in more detail.
628 LilyPond makes a sharp distinction between musical content and
629 layout. The alteration (@notation{flat}, @notation{natural} or
630 @notation{sharp}) of a note is part of the pitch, and is therefore
631 musical content. Whether an accidental (a @emph{printed} flat, natural
632 or sharp sign) is printed in front of the corresponding note is a
633 question of layout. Layout is something that follows rules, so
634 accidentals are printed automatically according to those rules. The
635 pitches in your music are works of art, so they will not be added
636 automatically, and you must enter what you want to hear.
640 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
646 No note has a printed accidental, but you must still add the
647 @samp{is} to @code{cis} and @code{fis}.
649 The code @samp{e} does not mean @qq{print a black dot just below
650 the first line of the staff.} Rather, it means @qq{there is a
651 note with pitch E-natural.} In the key of A-flat major, it
652 @emph{does} get an accidental:
654 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
659 Adding all alterations explicitly might require a little more
660 effort when typing, but the advantage is that
661 @notation{transposing} is easier, and accidentals can be printed
662 according to different conventions. For some examples how
663 accidentals can be printed according to different rules, see
664 @ruser{Automatic accidentals}.
668 Notation reference: @ruser{Accidentals}, @ruser{Automatic
669 accidentals}, @ruser{Key signature}.
671 Music glossary: @rglos{Pitch names}.
675 @subsection Ties and slurs
680 Music glossary: @rglos{tie}.
682 A @notation{tie} is created by appending a tilde @samp{~} to the
683 first note being tied.
685 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
693 Music glossary: @rglos{slur}.
695 A @notation{slur} is a curve drawn across many notes. The starting
696 note and ending note are marked with @samp{(} and @samp{)}
699 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
700 d4( c16) cis( d e c cis d) e( d4)
703 @cindex slurs, phrasing
704 @cindex phrasing slurs
705 @subheading Phrasing slurs
707 Music glossary: @rglos{phrasing}, @rglos{legato}.
709 Slurs to indicate longer @notation{phrasing} can be entered with
710 @code{\(} and @code{\)}. You can have both @notation{legato} slurs and
711 phrasing slurs at the same time, but you cannot have simultaneous legato
712 slurs or simultaneous phrasing slurs.
714 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
715 a8(\( ais b c) cis2 b'2 a4 cis,\)
720 @cindex slurs versus ties
721 @subheading Warnings: slurs vs. ties
723 Music glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
725 A @notation{slur} looks like a @notation{tie}, but it has a different
726 meaning. A tie simply makes the first note longer, and can only be
727 used on pairs of notes with the same pitch. Slurs indicate the
728 @notation{articulation} of notes, and can be used on larger groups of
729 notes. Slurs and ties can be nested.
731 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
732 c2~( c8 fis fis4 ~ fis2 g2)
737 Notation reference: @ruser{Ties}, @ruser{Slurs}, @ruser{Phrasing
741 @node Articulation and dynamics
742 @subsection Articulation and dynamics
747 @subheading Articulations
749 Music glossary: @rglos{articulation}.
751 Common @notation{articulations} can be added to a note using a
752 dash @samp{-} and a single character:
754 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
755 c-. c-- c-> c-^ c-+ c-_
759 @subheading Fingerings
761 Music glossary: @rglos{fingering}.
763 Similarly, @notation{fingering} indications can be added to a note using
764 a dash (@samp{-}) and the digit to be printed:
766 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
770 Articulations and fingerings are usually placed automatically, but
771 you can specify a direction using @samp{^} (up) or @samp{_}
772 (down). You can also use multiple articulations on the same note.
773 However, in most cases it is best to let LilyPond determine the
774 articulation directions.
776 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
777 c_-^1 d^. f^4_2-> e^-_+
782 Music glossary: @rglos{dynamics}, @rglos{crescendo},
785 @notation{Dynamic} signs are made by adding the markings (with a
786 backslash) to the note:
788 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
796 @notation{Crescendi} and @notation{decrescendi} are started with
797 the commands @code{\<} and @code{\>}. An ending dynamic, for
798 example @code{\f}, will finish the (de)crescendo, or the command
799 @code{\!} can be used:
801 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
807 Notation reference: @ruser{Articulations}, @ruser{Fingering
808 instructions}, @ruser{Dynamics}.
810 Music glossary: @rglos{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
834 @c Kurt: leave this alone for now.
838 Notation reference: @ruser{Writing text}.
841 @node Automatic and manual beams
842 @subsection Automatic and manual beams
844 Music glossary: @rglos{beam}.
846 @cindex beams, by hand
847 All @notation{beams} are drawn automatically:
849 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
850 a8 ais d ees r d c16 b a8
854 If you do not like the automatic beams, they may be overridden
855 manually. Mark the first note to be beamed with @samp{[} and the
856 last one with @samp{]}.
858 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
859 a8[ ais] d[ ees r d] a b
864 Notation reference: @ruser{Automatic beams}, @ruser{Manual beams}.
867 @node Advanced rhythmic commands
868 @subsection Advanced rhythmic commands
872 @cindex partial measure
873 @subheading Partial measure
875 Music glossary: @rglos{anacrusis}.
877 A pickup (or @notation{anacrusis}) is entered with the keyword
878 @code{\partial}. It is followed by a duration: @code{\partial 4}
879 is a quarter note pickup and @code{\partial 8} an eighth note.
881 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
890 Music glossary: @rglos{note value}, @rglos{triplet}.
892 @notation{Tuplets} are made with the @code{\times} keyword. It
893 takes two arguments: a fraction and a piece of music. The
894 duration of the piece of music is multiplied by the fraction.
895 Triplets make notes occupy 2/3 of their notated duration, so a
896 @notation{triplet} has 2/3 as its fraction
898 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
899 \times 2/3 { f8 g a }
901 \times 2/3 { f,8 g16[ a g a] }
908 @subheading Grace notes
910 Music glossary: @rglos{grace notes}, @rglos{appoggiatura}.
912 @notation{Grace notes} are created with the @code{\grace} command,
913 although they can also be created by prefixing a music expression
914 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
916 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
917 c2 \grace { a32[ b] } c2
918 c2 \appoggiatura b16 c2
919 c2 \acciaccatura b16 c2
924 Notation reference: @ruser{Grace notes}, @ruser{Tuplets},
928 @node Multiple notes at once
929 @section Multiple notes at once
931 This section introduces having more than one note at the same
932 time: multiple instruments, multiple staves for a single
933 instrument (i.e. piano), and chords.
935 Polyphony in music refers to having more than one voice occurring
936 in a piece of music. Polyphony in LilyPond refers to having more
937 than one voice on the same staff.
940 * Music expressions explained::
943 * Combining notes into chords::
944 * Single staff polyphony::
948 @node Music expressions explained
949 @subsection Music expressions explained
951 In LilyPond input files, music is represented by @emph{music
952 expressions}. A single note is a music expression:
954 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
958 Enclosing a note in braces creates a @emph{compound music
959 expression}. Here we have created a compound music expression
962 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
966 Putting a group of music expressions (e.g. notes) in braces means
967 that they are in sequence (i.e. each one follows the previous
968 one). The result is another music expression:
970 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
974 @subheading Simultaneous music expressions: multiple staves
976 Music glossary: @rglos{polyphony}.
978 This technique is useful for @notation{polyphonic} music. To
979 enter music with more voices or more staves, we combine
980 expressions in parallel. To indicate that two voices should play
981 at the same time, simply enter a simultaneous combination of music
982 expressions. A @q{simultaneous} music expression is formed by
983 enclosing expressions inside @code{<<} and @code{>>}. In the
984 following example, three sequences (all containing two separate
985 notes) are combined simultaneously:
987 @lilypond[verbatim,quote,ragged-right]
997 Note that we have indented each level of the input with a
998 different amount of space. LilyPond does not care how much (or
999 little) space there is at the beginning of a line, but indenting
1000 LilyPond code like this makes it much easier for humans to read.
1002 @warning{each note is relative to the previous note in
1003 the input, not relative to the @code{c''} in the initial
1004 @code{\\relative} command.}
1007 @subheading Simultaneous music expressions: single staff
1009 To determine the number of staves in a piece, LilyPond looks at
1010 the first expression. If it is a single note, there is one staff;
1011 if there is a simultaneous expression, there is more than one
1014 @lilypond[verbatim,quote,ragged-right]
1017 << { e f } { c <<b d>> } >>
1022 @cindex music expression
1023 @subheading Analogy: mathematical expressions
1025 This mechanism is similar to mathematical formulas: a big formula
1026 is created by composing small formulas. Such formulas are called
1027 expressions, and their definition is recursive so you can make
1028 arbitrarily complex and large expressions. For example,
1037 ((1 + 2) * 3) / (4 * 5)
1040 This is a sequence of expressions, where each expression is
1041 contained in the next (larger) one. The simplest expressions are
1042 numbers, and larger ones are made by combining expressions with
1043 operators (like @samp{+}, @samp{*} and @samp{/}) and parentheses.
1044 Like mathematical expressions, music expressions can be nested
1045 arbitrarily deep, which is necessary for complex music like
1049 @node Multiple staves
1050 @subsection Multiple staves
1052 LilyPond input files are constructed out of music expressions, as
1053 we saw in @ref{Music expressions explained}. If the score begins
1054 with simultaneous music expressions, LilyPond creates multiples
1055 staves. However, it is easier to see what happens if we create
1056 each staff explicitly.
1058 To print more than one staff, each piece of music that makes up a
1059 staff is marked by adding @code{\new Staff} before it. These
1060 @code{Staff} elements are then combined in parallel with @code{<<}
1063 @lilypond[verbatim,quote,ragged-right]
1066 \new Staff { \clef treble c }
1067 \new Staff { \clef bass c,, }
1072 The command @code{\new} introduces a @q{notation context.} A
1073 notation context is an environment in which musical events (like
1074 notes or @code{\clef} commands) are interpreted. For simple
1075 pieces, such notation contexts are created automatically. For
1076 more complex pieces, it is best to mark contexts explicitly.
1078 There are several types of contexts. @code{Score}, @code{Staff},
1079 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
1080 lyric texts and @code{ChordNames} prints chord names.
1082 In terms of syntax, prepending @code{\new} to a music expression
1083 creates a bigger music expression. In this way it resembles the
1084 minus sign in mathematics. The formula @math{(4+5)} is an
1085 expression, so @math{-(4+5)} is a bigger expression.
1087 Time signatures entered in one staff affects all other
1088 staves@footnote{This behavior may be changed if desired; for
1089 details, see @ruser{Polymetric notation}.}. On the other hand,
1090 the key signature of one staff does @emph{not} affect other
1093 @lilypond[verbatim,quote,ragged-right]
1096 \new Staff { \clef treble \time 3/4 c }
1097 \new Staff { \clef bass \key d \major c,, }
1106 @subsection Piano staves
1108 @cindex staff switch, manual
1109 @cindex cross staff voice, manual
1111 Music glossary: @rglos{brace}.
1113 Piano music is typeset in two staves connected by a
1115 Printing such a staff is similar to the polyphonic example in
1116 @ref{Multiple staves}. However, now this entire expression is
1117 inserted inside a @code{PianoStaff}:
1126 Here is a small example:
1128 @lilypond[verbatim,quote,ragged-right]
1131 \new Staff { \time 2/4 c4 e g g, }
1132 \new Staff { \clef bass c,, c' e c }
1139 Notation reference: @ruser{Piano music}.
1142 @node Combining notes into chords
1143 @subsection Combining notes into chords
1147 Music glossary: @rglos{chord}.
1149 @notation{Chords} can be made by surrounding pitches with single
1150 angle brackets. Angle brackets are the symbols @samp{<} and
1153 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1154 r4 <c e g>4 <c f a>2
1157 You can combine markings like beams and ties with chords. They
1158 must be placed outside the angle brackets.
1160 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1161 r4 <c e g>8[ <c f a>]~ <c f a>2
1164 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1165 r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
1169 @node Single staff polyphony
1170 @subsection Single staff polyphony
1173 @cindex multiple voices
1174 @cindex voices, more -- on a staff
1175 When different melodic lines are combined on a single staff they
1176 are printed as polyphonic voices; each voice has its own stems,
1177 slurs and beams, and the top voice has the stems up, while the
1178 bottom voice has them down.
1180 Entering such parts is done by entering each voice as a sequence
1181 (with @code{@{...@}}) and combining these simultaneously,
1182 separating the voices with @code{\\}
1184 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1191 For polyphonic music typesetting, spacer rests can also be
1192 convenient; these are rests that do not print. They are useful
1193 for filling up voices that temporarily do not play. Here is the
1194 same example with a spacer rest (@samp{s}) instead of a normal
1197 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1205 Again, these expressions can be nested arbitrarily.
1207 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1215 { <c g>1 ~ <c g>4 } \\
1223 Notation reference: @ruser{Simultaneous notes}.
1229 This section introduces vocal music and simple song sheets.
1232 * Setting simple songs::
1233 * Aligning lyrics to a melody::
1234 * Lyrics to multiple staves::
1238 @node Setting simple songs
1239 @subsection Setting simple songs
1244 Music glossary: @rglos{lyrics}.
1246 Here is the start of the melody to a nursery
1247 rhyme, @qq{Girls and boys come out to play}:
1249 @lilypond[verbatim,quote,ragged-right]
1253 d4 b8 c4 a8 d4 b8 g4
1257 The @notation{lyrics} can be set to these notes, combining both
1258 with the @code{\addlyrics} keyword. Lyrics are entered by
1259 separating each syllable with a space.
1261 @lilypond[verbatim,quote,ragged-right]
1266 d4 b8 c4 a8 d4 b8 g4
1269 Girls and boys come out to play,
1274 Note the curly brackets delimiting both the music and the lyrics,
1275 and the angle brackets @code{<< ... >>} around the whole piece to
1276 show that the music and lyrics are to occur at the same time.
1278 @node Aligning lyrics to a melody
1279 @subsection Aligning lyrics to a melody
1281 Music glossary: @rglos{melisma}, @rglos{extender line}.
1284 @cindex extender line
1288 The next line in the nursery rhyme is @q{The moon doth shine as
1289 bright as day}. Let's extend it:
1291 @lilypond[verbatim,quote,ragged-right]
1296 d4 b8 c4 a8 d4 b8 g4
1297 g8 a4 b8 c b a d4 b8 g4.
1300 Girls and boys come out to play,
1301 The moon doth shine as bright as day;
1306 We see the extra lyrics do not align properly with the notes. The
1307 word @q{shine} should be sung on two notes, not one. This is
1308 called a @notation{melisma}, a single syllable sung to more than one
1309 note. There are several ways to spread a syllable over multiple
1310 notes, the simplest being to add a slur across them (see @ref{Ties
1313 @lilypond[verbatim,quote,ragged-right]
1318 d4 b8 c4 a8 d4 b8 g4
1319 g8 a4 b8 c([ b)] a d4 b8 g4.
1322 Girls and boys come out to play,
1323 The moon doth shine as bright as day;
1328 Here we have also used manual beaming (the square brackets @code{[
1329 ]} ) to generate the beaming which is customarily used with lyrics
1330 (see @ref{Automatic and manual beams}).
1332 If a syllable extends over several notes or a single very long
1333 note an @notation{extender line} is usually drawn from the syllable
1334 extending under all the notes for that syllable. It is entered as
1335 two underscores @code{__}. Here is an example from the first
1336 three bars of Dido's Lament, from Purcell's Dido and Æneas:
1338 @lilypond[verbatim,quote,ragged-right]
1344 b c4.( bes8 a4. g8 fis4.) g8 fis1
1348 am laid __ in earth,
1353 None of the examples so far have involved words containing more
1354 than one syllable. Such words are usually split one syllable to a
1355 note, with hyphens between syllables. Such hyphens are entered as
1356 two dashes, resulting in a centered hyphen between the syllables.
1357 Here is an example showing this and everything we have learned so
1358 far about aligning lyrics to notes.
1360 @c no ragged-right here because otherwise the hyphens get lost,
1361 @c but the example is long enough to avoid looking strange.
1362 @lilypond[verbatim,quote]
1368 d4 g4 g a8( b) g4 g4
1372 A -- way in a __ man -- ger,
1373 no __ crib for a bed, __
1378 Some lyrics, especially those in Italian, require the opposite:
1379 setting more than one syllable to a single note. This is
1380 achieved by linking the syllables together with a single
1381 underscore @code{_} (with no spaces), or enclosing them in
1382 quotes. Here's an example from Rossini's Figaro, where
1383 @q{al} has to be sung on the same note as the @q{go} of
1384 @q{Largo} in Figaro's aria @q{Largo al factotum}:
1386 @c no ragged-right here because otherwise the hyphens get lost,
1387 @c but the example is long enough to avoid looking strange.
1388 @lilypond[verbatim,quote]
1394 c4.~ c8 d b c([ d)] b c d b c
1397 Lar -- go_al fac -- to -- tum del -- la cit -- tĂ
1405 More options, such as inserting explicit rhythms into lyrics,
1406 inserting lyric ties (e.g., between @q{go al}) above,
1407 alternative ways of handling melismata,
1408 and adding extra verses,
1409 are discussed in @ruser{Vocal music}.
1412 @node Lyrics to multiple staves
1413 @subsection Lyrics to multiple staves
1415 The simple approach using @code{\addlyrics} can be used for
1416 placing lyrics under more than one staff. Here is an
1417 example from Handel's Judas Maccabæus:
1419 @lilypond[verbatim,quote,ragged-right]
1427 c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
1430 Let flee -- cy flocks the hills a -- dorn, __
1434 r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
1437 Let flee -- cy flocks the hills a -- dorn,
1442 but scores any more complex than this simple example are
1443 better produced by separating out the staff structure
1444 from the notes and lyrics with variables. These are
1445 discussed later (see @ref{Organizing pieces with variables}).
1449 More options, such as putting multiple stanzas below the score,
1450 setting choral music, and lyrics to divided voices,
1451 are discussed in @ruser{Vocal music}.
1456 @section Final touches
1458 This is the final section of the tutorial; it demonstrates how to
1459 add the final touches to simple pieces, and provides an
1460 introduction to the rest of the manual.
1465 * Absolute note names::
1466 * Organizing pieces with variables::
1467 * After the tutorial::
1468 * How to read the manual::
1472 @node Version number
1473 @subsection Version number
1476 The @code{\version} statement records the version of LilyPond that
1477 was used to write the file:
1484 By convention, this is placed at the top of your LilyPond file.
1486 These annotations make future upgrades of LilyPond go more
1487 smoothly. Changes in the syntax are handled with a special
1488 program, @file{convert-ly}, and it uses @code{\version} to
1489 determine what rules to apply. For details, see
1490 @rprogram{Updating files with convert-ly}.
1494 @subsection Adding titles
1496 The title, composer, opus number, and similar information are
1497 entered in the @code{\header} block. This exists outside of the
1498 main music expression; the @code{\header} block is usually placed
1499 underneath the @ref{Version number}.
1510 @dots{} music @dots{}
1514 When the file is processed, the title and composer are printed
1515 above the music. More information on titling can be found in
1516 @ruser{Creating titles}.
1519 @node Absolute note names
1520 @subsection Absolute note names
1522 So far we have always used @code{\relative} to define pitches.
1523 This is the easiest way to enter most music, but another way of
1524 defining pitches exists: absolute mode.
1526 If you omit the @code{\relative}, LilyPond treats all pitches as
1527 absolute values. A @code{c'} will always mean middle C, a
1528 @code{b} will always mean the note one step below middle C, and a
1529 @code{g,} will always mean the note on the bottom staff of the
1532 @lilypond[verbatim,quote,ragged-right]
1540 Here is a four-octave scale:
1542 @lilypond[verbatim,quote,ragged-right]
1557 As you can see, writing a melody in the treble clef involves a lot
1558 of quote @code{'} marks. Consider this fragment from Mozart:
1560 @lilypond[verbatim,quote,ragged-right]
1564 cis''8. d''16 cis''8 e''4 e''8
1565 b'8. cis''16 b'8 d''4 d''8
1569 All these quotes makes the input less readable and it is a source
1570 of errors. With @code{\relative}, the previous example is much
1573 @lilypond[verbatim,quote,ragged-right]
1577 cis8. d16 cis8 e4 e8
1582 If you make a mistake with an octave mark (@code{'} or @code{,})
1583 while working in @code{\relative} mode, it is very obvious -- many
1584 notes will be in the wrong octave. When working in absolute mode,
1585 a single mistake will not be as visible, and will not be as easy
1588 However, absolute mode is useful for music which has large
1589 intervals, and is extremely useful for computer-generated LilyPond
1593 @node Organizing pieces with variables
1594 @subsection Organizing pieces with variables
1596 When all of the elements discussed earlier are combined to produce
1597 larger files, the music expressions get a lot bigger. In
1598 polyphonic music with many staves, the input files can become very
1599 confusing. We can reduce this confusion by using
1602 With variables (also known as identifiers or macros), we can break
1603 up complex music expressions. A variable is assigned as
1607 namedMusic = @{ @dots{} @}
1610 The contents of the music expression @code{namedMusic} can be used
1611 later by placing a backslash in front of the name
1612 (@code{\namedMusic}, just like a normal LilyPond command).
1613 Variables must be defined @emph{before} the main music
1616 @lilypond[verbatim,quote,ragged-right]
1617 violin = \new Staff { \relative c'' {
1620 cello = \new Staff { \relative c {
1633 The name of a variable must have alphabetic characters only, no
1634 numbers, underscores, or dashes.
1636 It is possible to use variables for many other types of objects in
1637 the input. For example,
1642 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1645 Depending on its contents, the variable can be used in different
1646 places. The following example uses the above variables:
1657 @node After the tutorial
1658 @subsection After the tutorial
1660 After finishing the tutorial, you should probably try writing a
1661 piece or two. Start by adding notes to one of the @ref{Templates}.
1662 If you need any notation that was not covered in the
1663 tutorial, look at the Notation Reference, starting with
1664 @ruser{Musical notation}. If you want to write for an instrument
1665 ensemble that is not covered in the templates, take a look at
1666 @ref{Extending the templates}.
1668 Once you have written a few short pieces, read the rest of the
1669 Learning Manual (chapters 3-5). There's nothing wrong with
1670 reading it now, of course! However, the rest of the Learning
1671 Manual assumes that you are familiar with LilyPond input. You may
1672 wish to skim these chapters right now, and come back to them after
1673 you have more experience.
1676 @node How to read the manual
1677 @subsection How to read the manual
1679 Many examples in the tutorial omitted a @code{\relative c'' @{
1680 ... @}} around the printed example, as we saw in
1681 @ref{How to read the tutorial}.
1683 In the rest of the manual, we are much more lax about the printed
1684 examples: sometimes they may have omitted a @code{\relative c'' @{
1685 ... @}}, but other times a different initial pitch may be used
1686 (such as @code{c'} or @code{c,,}), and in some cases the whole
1687 example is in absolute note mode! However, ambiguities like this
1688 only exist where the pitches are not important. In any example
1689 where the pitch matters, we have explicitly stated
1690 @code{\relative} or absolute-mode @code{@{ @}}.
1692 If you are still confused about the exact LilyPond input that was
1693 used in an example, read the HTML version (if you are not already
1694 doing so) and click on the picture of the music. This will
1695 display the exact input that LilyPond used to generate this
1698 For information about the structure of the rest of the manual, see
1699 @ref{About this manual}.