1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
11 Tutorial guidelines: (different from policy.txt!)
12 - unless you have a really good reason, use either
13 @lilypond[verbatim,quote,ragged-right]
15 @lilypond[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.
20 - use "aes" and "ees" instead of "as" and "es". I know it's not
21 correct Dutch naming, but let's not confuse people with this
22 until we get to the Basic notation chapter.
24 - Add "Music Glossary: @rglos{foo}" to the _top_ of the relevant
25 portions of the tutorial.
33 This tutorial starts with an introduction to the LilyPond music
34 language and how to produce printed music. After this first
35 contact we will explain how to create common musical notation.
39 * Single staff notation::
40 * Multiple notes at once::
49 This section gives a basic introduction to working with LilyPond.
54 * Working on text files::
55 * How to read the manual::
59 @node Compiling a file
60 @subsection Compiling a file
62 The first example demonstrates how to start working with LilyPond.
63 To create sheet music, we write a text file that specifies the
64 notation. For example, if we write:
73 the result looks like this:
75 @c in this case we don't want verbatim
76 @lilypond[quote,ragged-right]
82 @warning{Every piece of LilyPond input needs to have
83 @strong{@{ curly braces @}} placed around the input. The braces
84 should also be surrounded by a space unless they are at the
85 beginning or end of a line to avoid ambiguities. The braces may
86 be omitted in some examples in this manual, but don't forget them
87 in your own music! For more information about the display of
88 examples in the manual, see @ref{How to read the manual}.}
90 @cindex case sensitive
91 In addition, LilyPond input is @strong{case sensitive}. @code{
92 @{ c d e @}} is valid input; @code{@{ C D E @}} will produce an
97 @subheading Entering music and viewing output
100 @cindex viewing music
102 In this section we will explain what commands to run and how to
103 view or print the output.
105 Note that there are several other text editors available with
106 better support for LilyPond. For more information, see
107 @rprogram{Text editor support}.
109 @warning{the first time you ever run LilyPond, it may take a
110 minute or two because all of the system fonts have to be analyzed
111 first. After this, LilyPond will be much faster!}
113 @subsubheading MacOS X
115 If you double click @code{LilyPond.app}, it will open with an
116 example file. Save it, for example, to @file{test.ly} on your
117 Desktop, and then process it with the menu command @code{Compile >
118 Typeset File}. The resulting PDF file will be displayed on your
121 For future use of LilyPond, you should begin by selecting @q{New}
122 or @q{Open}. You must save your file before typesetting it. If
123 any errors occur in processing, please see the log window.
126 @subsubheading Windows
128 On Windows, if you double-click in the LilyPond icon on the
129 Desktop, it will open a simple text editor with an example file.
130 Save it, for example, to @file{test.ly} on your Desktop and then
131 double-click on the file to process it (the file icon looks like a
132 note). After some seconds, you will get a file @file{test.pdf} on
133 your desktop. Double-click on this PDF file to view the typeset
134 score. An alternative method to process the @file{test.ly} file
135 is to drag and drop it onto the LilyPond icon using your mouse
138 To edit an existing @file{.ly} file, right-click on it and
139 select @qq{Edit source}. To get an empty file to start from, run
140 the editor as described above and use @qq{New} in
143 Double-clicking the file does not only result in a PDF file, but
144 also produces a @file{.log} file that contains some information on
145 what LilyPond has done to the file. If any errors occur, please
150 Create a file (such as @file{test.ly}) and enter:
158 To process @file{test.ly}, proceed as follows:
165 You will see something resembling:
172 Interpreting music...
173 Preprocessing graphical objects...
174 Finding the ideal number of pages...
175 Fitting music on 1 page...
177 Layout output to `test.ps'...
178 Converting to `test.pdf'...
182 @node Simple notation
183 @subsection Simple notation
185 LilyPond will add some notation elements automatically. In the
186 next example, we have only specified four pitches, but LilyPond
187 has added a clef, time signature, and rhythms.
189 @lilypond[verbatim,quote,ragged-right]
196 This behavior may be altered, but in most cases these automatic
202 Music Glossary: @rglos{pitch}, @rglos{interval},
203 @rglos{scale}, @rglos{middle C}, @rglos{octave},
206 The easiest way to enter notes is by using @code{\relative} mode.
207 In this mode, the octave is chosen automatically by assuming the
208 following note is always to be placed closest to the previous
209 note, i.e., it is to be placed in the octave which is within three
210 staff spaces of the previous note. We begin by entering the most
211 elementary piece of music, a @notation{scale}, in which every note
212 is within just one staff space of the previous note.
214 @lilypond[verbatim,quote,ragged-right]
215 \relative c' { % set the starting point to middle C
221 The initial note is @notation{middle C}. Each successive note is
222 placed closest to the previous note -- in other words, the first
223 @code{c} is the closest C to middle C. This is followed by the
224 closest D to the previous note. We can create melodies which have
225 larger intervals, still using only @code{\relative} mode:
227 @lilypond[verbatim,quote,ragged-right]
235 It is not necessary for the first note of the melody to start on
236 the note which specifies the starting pitch. In the previous
237 example, the first note -- the @code{d} -- is the closest D to
240 By adding (or removing) quotes @code{'} or commas @code{,} from
241 the @code{\relative c' @{} command, we can change the starting
244 @lilypond[verbatim,quote,ragged-right]
245 \relative c'' { % one octave above middle C
250 Relative mode can be confusing initially, but is the easiest way
251 to enter most melodies. Let us see how this relative calculation
252 works in practice. Starting from a B, which is on the middle line
253 in a treble clef, you can reach a C, D and E within 3 staff spaces
254 going up, and an A, G and F within 3 staff spaces going down. So
255 if the note following a B is a C, D or F it will be assumed to be
256 above the B, and an A, G or F will be assumed to be below.
258 @lilypond[verbatim,quote,ragged-right]
260 b c % c is 1 staff space up, so is the c above
261 b d % d is 2 up or 5 down, so is the d above
262 b e % e is 3 up or 4 down, so is the e above
263 b a % a is 4 up or 3 down, so is the a below
264 b g % g is 5 up or 2 down, so is the g below
265 b f % f is 6 up or 1 down, so is the f below
269 Exactly the same happens even when any of these notes are
270 sharpened or flattened. @notation{Accidentals} are
271 @strong{totally ignored} in the calculation of relative position.
272 Precisely the same staff space counting is done from a note at any
273 other position on the staff.
275 To add intervals that are larger than three staff spaces, we can
276 raise the @notation{octave} by adding a single quote @code{'} (or
277 apostrophe) to the note name. We can lower the octave by adding a
278 comma @code{,} to the note name.
280 @lilypond[verbatim,quote,ragged-right]
288 To change a note by two (or more!) octaves, we use multiple
289 @code{''} or @code{,,} -- but be careful that you use two single
290 quotes @code{''} and not one double quote @code{"}@tie{}! The
291 initial value in @code{\relative c'} may also be modified like
295 @subheading Durations (rhythms)
297 Music Glossary: @rglos{beam}, @rglos{duration},
298 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
301 The @notation{duration} of a note is specified by a number after
302 the note name. @code{1} for a @notation{whole note}, @code{2} for
303 a @notation{half note}, @code{4} for a @notation{quarter note} and
304 so on. @notation{Beams} are added automatically.
306 If you do not specify a duration, the previous duration is used
307 for the next note. The duration of the first note defaults to a
310 @lilypond[verbatim,quote,ragged-right]
314 a16 a a a a32 a a a a64 a a a a a a a a2
318 To create @notation{dotted notes}, add a dot @code{.} to the
319 duration number. The duration of a dotted note must be stated
320 explicitly (i.e., with a number).
322 @lilypond[verbatim,quote,ragged-right]
332 Music Glossary: @rglos{rest}.
334 A @notation{rest} is entered just like a note with the name
337 @lilypond[verbatim,quote,ragged-right]
345 @subheading Time signature
347 Music Glossary: @rglos{time signature}.
349 The @notation{time signature} can be set with the @code{\time}
352 @lilypond[verbatim,quote,ragged-right]
366 Music Glossary: @rglos{clef}.
368 The @notation{clef} can be set using the @code{\clef} command:
370 @lilypond[verbatim,quote,ragged-right]
384 @subheading All together
386 Here is a small example showing all these elements together:
388 @lilypond[verbatim,quote,ragged-right]
400 Notation Reference: @ruser{Writing pitches},
401 @ruser{Writing rhythms}, @ruser{Writing rests},
402 @ruser{Time signature}, @ruser{Clef}.
405 @node Working on text files
406 @subsection Working on text files
408 LilyPond input files are similar to source files in many common
409 programming languages. They are case sensitive, and white-space
410 is generally equivalent. Expressions are formed with curly braces
411 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
414 If the previous sentences sound like nonsense, don't worry! We'll
415 explain what all these terms mean:
419 @cindex case sensitive
421 @strong{Case sensitive}:
422 it matters whether you enter a letter in lower case (e.g. @code{a,
423 b, s, t}) or upper case (e.g. @code{A, B, S, T}). Notes are
424 lower case: @code{@{ c d e @}} is valid input; @code{@{ C D E @}}
425 will produce an error message.
428 @strong{Whitespace insensitive}:
429 it does not matter how many spaces (or new lines) you add.
430 @code{@{ c d e @}} means the same thing as @code{@{ c @tie{}
431 @tie{} @tie{} d e @}} and:
439 Of course, the previous example is hard to read. A good rule of
440 thumb is to indent code blocks with either a tab or two spaces:
449 @strong{Expressions}:
450 every piece of LilyPond input needs to have @strong{@{ curly
451 braces @}} placed around the input. These braces tell LilyPond
452 that the input is a single music expression, just like parentheses
453 @code{()} in mathematics. The braces should be surrounded by a
454 space unless they are at the beginning or end of a line to avoid
457 A function (such as @code{\relative @{ @}}) also counts as a
458 single music expression.
462 @cindex block comment
465 a comment is a remark for the human reader of the music input; it
466 is ignored while parsing, so it has no effect on the printed
467 output. There are two types of comments. The percent symbol
468 @code{%} introduces a line comment; anything after @code{%} on
469 that line is ignored. A block comment marks a whole section of
470 music input as a comment. Anything that is enclosed in @code{%@{}
471 and @code{%@}} is ignored. (Comments do not nest.) The following
472 fragment shows possible uses for comments:
475 % notes for twinkle twinkle follow
479 This line, and the notes below
480 are ignored, since they are in a
490 @node How to read the manual
491 @subsection How to read the manual
493 LilyPond input must be surrounded by @{ @} marks or a
494 @code{\relative c'' @{ ... @}}, as we saw in @ref{Working on text
495 files}. For the rest of this manual, most examples will omit
496 this. To replicate the examples, you may copy and paste the
497 displayed input but you @strong{must} add the @code{\relative c''
502 ... example goes here...
506 Why omit the braces? Most examples in this manual can be inserted
507 into the middle of a longer piece of music. For these examples,
508 it does not make sense to add @code{\relative c'' @{ @}} -- you
509 should not place a @code{\relative} inside another
510 @code{\relative}! If we included @code{\relative c'' @{ @}}
511 around every example, you would not be able to copy a small
512 documentation example and paste it inside a longer piece of your
513 own. Most people want to add material to an existing piece, so we
514 format the manual this way.
517 @subheading Clickable examples
519 Many people learn programs by trying and fiddling around with the
520 program. This is also possible with LilyPond. If you click on a
521 picture in the HTML version of this manual, you will see the exact
522 LilyPond input that was used to generate that image. Try it on
526 @lilypond[quote,ragged-right]
528 c-\markup { \bold \huge { Click here. } }
532 By cutting and pasting everything in the @qq{ly snippet} section,
533 you have a starting template for experiments. To see exactly the
534 same output (line-width and all), copy everything from @qq{Start
535 cut-&-pastable section} to the bottom of the file.
540 There are more tips for constructing input files in
541 @ref{Suggestions for writing LilyPond files}.
545 @node Single staff notation
546 @section Single staff notation
548 This section introduces common notation that is used for one voice
552 * Accidentals and key signatures::
554 * Articulation and dynamics::
556 * Automatic and manual beams::
557 * Advanced rhythmic commands::
561 @node Accidentals and key signatures
562 @subsection Accidentals and key signatures
564 @subheading Accidentals
566 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
567 @rglos{double flat}, @rglos{accidental}.
569 A @notation{sharp} pitch is made by adding @code{is} to the name,
570 and a @notation{flat} pitch by adding @code{es}. As you might
571 expect, a @notation{double sharp} or @notation{double flat} is
572 made by adding @code{isis} or @code{eses}. This syntax is derived
573 from note naming conventions in Nordic and Germanic languages,
574 like German and Dutch. To use other names for
575 @notation{accidentals}, see @ruser{Note names in other languages}.
577 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
578 cis1 ees fisis, aeses
581 @cindex key signature, setting
582 @subheading Key signatures
584 Music Glossary: @rglos{key signature}, @rglos{major},
587 The @notation{key signature} is set with the command @code{\key}
588 followed by a pitch and @code{\major} or @code{\minor}.
590 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
599 @subheading Warning: key signatures and pitches
601 Music Glossary: @rglos{accidental}, @rglos{key signature},
602 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
603 @rglos{transposition}.
605 To determine whether to print an @notation{accidental}, LilyPond
606 examines the pitches and the @notation{key signature}. The key
607 signature only affects the @emph{printed} accidentals, not the
608 note's @notation{pitch}! This is a feature that often causes
609 confusion to newcomers, so let us explain it in more detail.
611 LilyPond makes a sharp distinction between musical content and
612 layout. The alteration (@notation{flat}, @notation{natural} or
613 @notation{sharp}) of a note is part of the pitch, and is therefore
614 musical content. Whether an accidental (a @emph{printed} flat,
615 natural or sharp sign) is printed in front of the corresponding
616 note is a question of layout. Layout is something that follows
617 rules, so accidentals are printed automatically according to those
618 rules. The pitches in your music are works of art, so they will
619 not be added automatically, and you must enter what you want to
624 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
630 No note has a printed accidental, but you must still add the
631 @code{is} to @code{cis} and @code{fis}.
633 The code @code{e} does not mean @qq{print a black dot just below
634 the first line of the staff.} Rather, it means @qq{there is a
635 note with pitch E-natural.} In the key of A-flat major, it
636 @emph{does} get an accidental:
638 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
643 Adding all alterations explicitly might require a little more
644 effort when typing, but the advantage is that
645 @notation{transposing} is easier, and accidentals can be printed
646 according to different conventions. For some examples how
647 accidentals can be printed according to different rules, see
648 @ruser{Automatic accidentals}.
652 Notation Reference: @ruser{Note names in other languages},
653 @ruser{Accidentals}, @ruser{Automatic accidentals},
654 @ruser{Key signature}.
656 Music Glossary: @rglos{Pitch names}.
660 @subsection Ties and slurs
665 Music Glossary: @rglos{tie}.
667 A @notation{tie} is created by appending a tilde @code{~} to the
668 first note being tied.
670 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
678 Music Glossary: @rglos{slur}.
680 A @notation{slur} is a curve drawn across many notes. The
681 starting note and ending note are marked with @code{(} and
682 @code{)} respectively.
684 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
685 d4( c16) cis( d e c cis d) e( d4)
688 @cindex slurs, phrasing
689 @cindex phrasing slurs
690 @subheading Phrasing slurs
692 Music Glossary: @rglos{phrasing}, @rglos{legato}.
694 Slurs to indicate longer @notation{phrasing} can be entered with
695 @code{\(} and @code{\)}. You can have both @notation{legato}
696 slurs and phrasing slurs at the same time, but you cannot have
697 simultaneous legato slurs or simultaneous phrasing slurs.
699 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
700 a8(\( ais b c) cis2 b'2 a4 cis,\)
705 @cindex slurs versus ties
706 @subheading Warnings: slurs vs. ties
708 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
710 A @notation{slur} looks like a @notation{tie}, but it has a
711 different meaning. A tie simply makes the first note longer, and
712 can only be used on pairs of notes with the same pitch. Slurs
713 indicate the @notation{articulation} of notes, and can be used on
714 larger groups of notes. Slurs and ties can be nested.
716 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
717 c2~( c8 fis fis4 ~ fis2 g2)
722 Notation Reference: @ruser{Ties}, @ruser{Slurs},
723 @ruser{Phrasing slurs}.
726 @node Articulation and dynamics
727 @subsection Articulation and dynamics
732 @subheading Articulations
734 Music Glossary: @rglos{articulation}.
736 Common @notation{articulations} can be added to a note using a
737 dash @code{-} and a single character:
739 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
740 c-. c-- c-> c-^ c-+ c-_
744 @subheading Fingerings
746 Music Glossary: @rglos{fingering}.
749 Similarly, @notation{fingering} indications can be added to a note
750 using a dash (@code{-}) and the digit to be printed:
752 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
756 Articulations and fingerings are usually placed automatically, but
757 you can specify a direction by replacing the dash (@code{-}) with
758 @code{^} (up) or @code{_} (down). You can also use multiple
759 articulations on the same note. However, in most cases it is best
760 to let LilyPond determine the articulation directions.
762 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
763 c_-^1 d^. f^4_2-> e^-_+
768 Music Glossary: @rglos{dynamics}, @rglos{crescendo},
771 @notation{Dynamic} signs are made by adding the markings (with a
772 backslash) to the note:
774 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
782 @notation{Crescendi} and @notation{decrescendi} are started with
783 the commands @code{\<} and @code{\>}. An ending dynamic, for
784 example @code{\f}, will finish the (de)crescendo, or the command
785 @code{\!} can be used:
787 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
793 Notation Reference: @ruser{Articulations},
794 @ruser{Fingering instructions}, @ruser{Dynamics}.
798 @subsection Adding text
800 Text may be added to your scores:
802 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
806 Extra formatting may be added with the @code{\markup} command:
808 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
809 c1^\markup{ \bold espr}
811 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
818 Notation Reference: @ruser{Writing text}.
821 @node Automatic and manual beams
822 @subsection Automatic and manual beams
824 Music Glossary: @rglos{beam}.
826 @cindex beams, by hand
827 All @notation{beams} are drawn automatically:
829 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
830 a8 ais d ees r d c16 b a8
834 If you do not like the automatic beams, they may be overridden
835 manually. Mark the first note to be beamed with @code{[} and the
836 last one with @code{]}.
838 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
839 a8[ ais] d[ ees r d] a b
844 Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
847 @node Advanced rhythmic commands
848 @subsection Advanced rhythmic commands
852 @cindex partial measure
853 @subheading Partial measure
855 Music Glossary: @rglos{anacrusis}.
857 A pickup (or @notation{anacrusis}) is entered with the keyword
858 @code{\partial}. It is followed by a duration: @code{\partial 4}
859 is a quarter note pickup and @code{\partial 8} an eighth note.
861 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
870 Music Glossary: @rglos{note value}, @rglos{triplet}.
872 @notation{Tuplets} are made with the @code{\times} keyword. It
873 takes two arguments: a fraction and a piece of music. The
874 duration of the piece of music is multiplied by the fraction.
875 Triplets make notes occupy 2/3 of their notated duration, so a
876 @notation{triplet} has 2/3 as its fraction
878 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
879 \times 2/3 { f8 g a }
881 \times 2/3 { f,8 g16[ a g a] }
888 @subheading Grace notes
890 Music Glossary: @rglos{grace notes}, @rglos{acciacccatura},
891 @rglos{appoggiatura}.
893 @notation{Grace notes} are created with the @code{\grace} command,
894 although they can also be created by prefixing a music expression
895 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
897 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
898 c2 \grace { a32[ b] } c2
899 c2 \appoggiatura b16 c2
900 c2 \acciaccatura b16 c2
905 Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
909 @node Multiple notes at once
910 @section Multiple notes at once
912 This section introduces having more than one note at the same
913 time: multiple instruments, multiple staves for a single
914 instrument (i.e. piano), and chords.
916 Polyphony in music refers to having more than one voice occurring
917 in a piece of music. Polyphony in LilyPond refers to having more
918 than one voice on the same staff.
921 * Music expressions explained::
924 * Combining notes into chords::
925 * Single staff polyphony::
929 @node Music expressions explained
930 @subsection Music expressions explained
932 In LilyPond input files, music is represented by @emph{music
933 expressions}. A single note is a music expression:
935 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
939 Enclosing a note in braces creates a @emph{compound music
940 expression}. Here we have created a compound music expression
943 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
947 Putting a group of music expressions (e.g. notes) in braces means
948 that they are in sequence (i.e. each one follows the previous
949 one). The result is another music expression:
951 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
956 @cindex music expression
957 @subheading Analogy: mathematical expressions
959 This mechanism is similar to mathematical formulas: a big formula
960 is created by composing small formulas. Such formulas are called
961 expressions, and they can contain other music expressions, so you
962 can make arbitrarily complex and large expressions. For example,
971 ((1 + 2) * 3) / (4 * 5)
974 This is a sequence of expressions, where each expression is
975 contained in the next (larger) one. The simplest expressions are
976 numbers, and larger ones are made by combining expressions with
977 operators (like @code{+}, @code{*} and @code{/}) and parentheses.
978 Like mathematical expressions, music expressions can be nested
979 arbitrarily deep, which is necessary for complex music like
983 @subheading Simultaneous music expressions: multiple staves
985 Music Glossary: @rglos{polyphony}.
987 This technique is useful for @notation{polyphonic} music. To
988 enter music with more voices or more staves, we combine
989 expressions in parallel. To indicate that two voices should play
990 at the same time, simply enter a simultaneous combination of music
991 expressions. A @q{simultaneous} music expression is formed by
992 enclosing expressions inside @code{<<} and @code{>>}. In the
993 following example, three sequences (all containing two separate
994 notes) are combined simultaneously:
996 @lilypond[verbatim,quote,ragged-right]
1006 Note that we have indented each level of the input with a
1007 different amount of space. LilyPond does not care how much (or
1008 little) space there is at the beginning of a line, but indenting
1009 LilyPond code like this makes it much easier for humans to read.
1011 @warning{each note is relative to the previous note in
1012 the input, not relative to the @code{c''} in the initial
1013 @code{\\relative} command.}
1016 @subheading Simultaneous music expressions: single staff
1018 To determine the number of staves in a piece, LilyPond looks at
1019 the first expression. If it is a single note, there is one staff;
1020 if there is a simultaneous expression, there is more than one
1023 @lilypond[verbatim,quote,ragged-right]
1026 << { e f } { c <<b d>> } >>
1030 @node Multiple staves
1031 @subsection Multiple staves
1033 LilyPond input files are constructed out of music expressions, as
1034 we saw in @ref{Music expressions explained}. If the score begins
1035 with simultaneous music expressions, LilyPond creates multiples
1036 staves. However, it is easier to see what happens if we create
1037 each staff explicitly.
1039 To print more than one staff, each piece of music that makes up a
1040 staff is marked by adding @code{\new Staff} before it. These
1041 @code{Staff} elements are then combined in parallel with @code{<<}
1044 @lilypond[verbatim,quote,ragged-right]
1047 \new Staff { \clef treble c }
1048 \new Staff { \clef bass c,, }
1053 The command @code{\new} introduces a @q{notation context.} A
1054 notation context is an environment in which musical events (like
1055 notes or @code{\clef} commands) are interpreted. For simple
1056 pieces, such notation contexts are created automatically. For
1057 more complex pieces, it is best to mark contexts explicitly.
1059 There are several types of contexts. @code{Score}, @code{Staff},
1060 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
1061 lyric texts and @code{ChordNames} prints chord names.
1063 In terms of syntax, prepending @code{\new} to a music expression
1064 creates a bigger music expression. In this way it resembles the
1065 minus sign in mathematics. The formula @math{(4+5)} is an
1066 expression, so @math{-(4+5)} is a bigger expression.
1068 Time signatures entered in one staff affects all other staves by
1069 default. On the other hand, the key signature of one staff does
1070 @emph{not} affect other staves. This different default behaviour
1071 is because scores with transposing instruments are more common
1072 than polyrhythmic scores.
1074 @lilypond[verbatim,quote,ragged-right]
1077 \new Staff { \clef treble \key d \major \time 3/4 c }
1078 \new Staff { \clef bass c,, }
1087 @subsection Staff groups
1093 Music Glossary: @rglos{brace}.
1095 Piano music is typeset in two staves connected by a
1097 Printing such a staff is similar to the polyphonic example in
1098 @ref{Multiple staves}. However, now this entire expression is
1099 inserted inside a @code{PianoStaff}:
1108 Here is a small example:
1110 @lilypond[verbatim,quote,ragged-right]
1113 \new Staff { \time 2/4 c4 e g g, }
1114 \new Staff { \clef bass c,, c' e c }
1119 Other staff groupings are introduced with
1120 @code{\new GrandStaff,} suitable for orchestral
1121 scores, and @code{\new ChoirStaff,} suitable for
1122 vocal scores. These staff groups each form another
1123 type of context, one that generates the brace at the
1124 left end of every system and also controls the extent
1129 Notation Reference: @ruser{Piano music},
1130 @ruser{Displaying staves}.
1133 @node Combining notes into chords
1134 @subsection Combining notes into chords
1138 Music Glossary: @rglos{chord}.
1140 @notation{Chords} can be made by surrounding pitches with single
1141 angle brackets. Note that all the notes in a chord must have the
1142 same duration, and that duration is placed after the closing
1145 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1146 r4 <c e g>4 <c f a>2
1149 Think of chords as almost equivalent to single notes:
1150 almost everything you can attach to a single note can be attached
1151 to a chord, and everything must go @emph{outside} the angle
1152 brackets. For example, you can combine markings like beams and
1153 ties with chords. They must be placed outside the angle brackets.
1155 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1156 r4 <c e g>8[ <c f a>]~ <c f a>2
1159 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1160 r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
1164 @node Single staff polyphony
1165 @subsection Single staff polyphony
1168 @cindex multiple voices
1169 @cindex voices, more -- on a staff
1170 When different melodic lines are combined on a single staff they
1171 are printed as polyphonic voices; each voice has its own stems,
1172 slurs and beams, and the top voice has the stems up, while the
1173 bottom voice has them down.
1175 Entering such parts is done by entering each voice as a sequence
1176 (with @code{@{...@}}) and combining these simultaneously,
1177 separating the voices with @code{\\}
1179 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1186 For polyphonic music typesetting, spacer rests can also be
1187 convenient; these are rests that do not print. They are useful
1188 for filling up voices that temporarily do not play. Here is the
1189 same example with a spacer rest (@code{s}) instead of a normal
1192 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1200 Again, these expressions can be nested arbitrarily.
1202 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1210 { <c g>1 ~ <c g>4 } \\
1218 Notation Reference: @ruser{Simultaneous notes}.
1224 This section introduces vocal music and simple song sheets.
1227 * Setting simple songs::
1228 * Aligning lyrics to a melody::
1229 * Lyrics to multiple staves::
1233 @node Setting simple songs
1234 @subsection Setting simple songs
1239 Music Glossary: @rglos{lyrics}.
1241 Here is the start of the melody to a nursery
1242 rhyme, @qq{Girls and boys come out to play}:
1244 @lilypond[verbatim,quote,ragged-right]
1248 d4 b8 c4 a8 d4 b8 g4
1252 The @notation{lyrics} can be set to these notes, combining both
1253 with the @code{\addlyrics} keyword. Lyrics are entered by
1254 separating each syllable with a space.
1256 @lilypond[verbatim,quote,ragged-right]
1261 d4 b8 c4 a8 d4 b8 g4
1264 Girls and boys come out to play,
1269 Note the curly brackets delimiting both the music and the lyrics,
1270 and the double angle brackets @code{<< ... >>} around the whole
1271 piece to show that the music and lyrics are to occur at the same
1274 @node Aligning lyrics to a melody
1275 @subsection Aligning lyrics to a melody
1277 Music Glossary: @rglos{melisma}, @rglos{extender line}.
1280 @cindex extender line
1284 The next line in the nursery rhyme is @q{The moon doth shine as
1285 bright as day}. Let's extend it:
1287 @lilypond[verbatim,quote,ragged-right]
1292 d4 b8 c4 a8 d4 b8 g4
1293 g8 a4 b8 c b a d4 b8 g4.
1296 Girls and boys come out to play,
1297 The moon doth shine as bright as day;
1302 We see the extra lyrics do not align properly with the notes. The
1303 word @q{shine} should be sung on two notes, not one. This is
1304 called a @notation{melisma}, a single syllable sung to more than
1305 one note. There are several ways to spread a syllable over
1306 multiple notes, the simplest being to add a slur across them (see
1307 @ref{Ties and slurs}):
1309 @lilypond[verbatim,quote,ragged-right]
1314 d4 b8 c4 a8 d4 b8 g4
1315 g8 a4 b8 c([ b)] a d4 b8 g4.
1318 Girls and boys come out to play,
1319 The moon doth shine as bright as day;
1324 Here we have also used manual beaming (the square brackets @code{[
1325 ]} ) to generate the beaming which is customarily used with lyrics
1326 (see @ref{Automatic and manual beams}).
1328 As an alternative to using slurs, the melismata may be indicated
1329 just in the lyrics by using an underscore, @code{_}, for each
1330 note that should be included in the melisma:
1332 @lilypond[verbatim,quote,ragged-right]
1337 d4 b8 c4 a8 d4 b8 g4
1338 g8 a4 b8 c[ b] a d4 b8 g4.
1341 Girls and boys come out to play,
1342 The moon doth shine _ as bright as day;
1347 If a syllable extends over several notes or a single very long
1348 note an @notation{extender line} is usually drawn from the
1349 syllable extending under all the notes for that syllable. It is
1350 entered as two underscores @code{__}. Here is an example from the
1351 first three bars of Dido's Lament, from Purcell's Dido and Æneas:
1353 @lilypond[verbatim,quote,ragged-right]
1359 b c4.( bes8 a4. g8 fis4.) g8 fis1
1363 am laid __ in earth,
1368 None of the examples so far have involved words containing more
1369 than one syllable. Such words are usually split one syllable to a
1370 note, with hyphens between syllables. Such hyphens are entered as
1371 two dashes, resulting in a centered hyphen between the syllables.
1372 Here is an example showing this and everything we have learned so
1373 far about aligning lyrics to notes.
1375 @c no ragged-right here because otherwise the hyphens get lost,
1376 @c but the example is long enough to avoid looking strange.
1377 @lilypond[verbatim,quote]
1383 d4 g4 g a8( b) g4 g4
1387 A -- way in a __ man -- ger,
1388 no __ crib for a bed, __
1393 Some lyrics, especially those in Italian, require the opposite:
1394 setting more than one syllable to a single note. This is
1395 achieved by linking the syllables together with a single
1396 underscore @code{_} (with no spaces), or enclosing them in
1397 quotes. Here's an example from Rossini's Figaro, where
1398 @q{al} has to be sung on the same note as the @q{go} of
1399 @q{Largo} in Figaro's aria @q{Largo al factotum}:
1401 @c no ragged-right here because otherwise the hyphens get lost,
1402 @c but the example is long enough to avoid looking strange.
1403 @lilypond[verbatim,quote]
1409 c4.~ c8 d b c([ d)] b c d b c
1412 Lar -- go_al fac -- to -- tum del -- la cit -- tà
1420 Notation Reference: @ruser{Vocal music}.
1423 @node Lyrics to multiple staves
1424 @subsection Lyrics to multiple staves
1426 The simple approach using @code{\addlyrics} can be used for
1427 placing lyrics under more than one staff. Here is an
1428 example from Handel's Judas Maccabæus:
1430 @lilypond[verbatim,quote,ragged-right]
1438 c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
1441 Let flee -- cy flocks the hills a -- dorn, __
1445 r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
1448 Let flee -- cy flocks the hills a -- dorn,
1454 but scores any more complex than this simple example are
1455 better produced by separating out the staff structure
1456 from the notes and lyrics with variables. These
1457 discussed in @ref{Organizing pieces with variables}.
1461 Notation Reference: @ruser{Vocal music}.
1466 @section Final touches
1468 This is the final section of the tutorial; it demonstrates how to
1469 add the final touches to simple pieces, and provides an
1470 introduction to the rest of the manual.
1473 * Organizing pieces with variables::
1476 * Absolute note names::
1477 * After the tutorial::
1481 @node Organizing pieces with variables
1482 @subsection Organizing pieces with variables
1484 When all of the elements discussed earlier are combined to produce
1485 larger files, the music expressions get a lot bigger. In
1486 polyphonic music with many staves, the input files can become very
1487 confusing. We can reduce this confusion by using
1490 With variables (also known as identifiers or macros), we can break
1491 up complex music expressions. A variable is assigned as
1495 namedMusic = @{ @dots{} @}
1498 The contents of the music expression @code{namedMusic} can be used
1499 later by placing a backslash in front of the name
1500 (@code{\namedMusic}, just like a normal LilyPond command).
1502 @lilypond[verbatim,quote,ragged-right]
1503 violin = \new Staff { \relative c'' {
1506 cello = \new Staff { \relative c {
1519 The name of a variable must have alphabetic characters only, no
1520 numbers, underscores, or dashes.
1522 Variables must be defined @emph{before} the main music
1523 expression, but may be used as many times as required anywhere after
1524 they have been defined. They may even be used in a later definition
1525 of another variable, giving a way of shortening the input if a
1526 section of music is repeated many times.
1528 @lilypond[verbatim,quote,ragged-right]
1529 tripletA = \times 2/3 { c,8 e g }
1530 barA = { \tripletA \tripletA \tripletA \tripletA }
1537 Variables may be used for many other types of objects in
1538 the input. For example,
1543 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1546 Depending on its contents, the variable can be used in different
1547 places. The following example uses the above variables:
1558 @node Version number
1559 @subsection Version number
1562 The @code{\version} statement records the version of LilyPond that
1563 was used to write the file:
1570 By convention, this is placed at the top of your LilyPond file.
1572 These annotations make future upgrades of LilyPond go more
1573 smoothly. Changes in the syntax are handled with a special
1574 program, @file{convert-ly}, and it uses @code{\version} to
1575 determine what rules to apply. For details, see
1576 @rprogram{Updating files with convert-ly}.
1580 @subsection Adding titles
1582 The title, composer, opus number, and similar information are
1583 entered in the @code{\header} block. This exists outside of the
1584 main music expression; the @code{\header} block is usually placed
1585 underneath the @ref{Version number}.
1596 @dots{} music @dots{}
1600 When the file is processed, the title and composer are printed
1601 above the music. More information on titling can be found in
1602 @ruser{Creating titles}.
1605 @node Absolute note names
1606 @subsection Absolute note names
1608 So far we have always used @code{\relative} to define pitches.
1609 This is the easiest way to enter most music, but another way of
1610 defining pitches exists: absolute mode.
1612 If you omit the @code{\relative}, LilyPond treats all pitches as
1613 absolute values. A @code{c'} will always mean middle C, a
1614 @code{b} will always mean the note one step below middle C, and a
1615 @code{g,} will always mean the note on the bottom staff of the
1618 @lilypond[verbatim,quote,ragged-right]
1626 Here is a four-octave scale:
1628 @lilypond[verbatim,quote,ragged-right]
1643 As you can see, writing a melody in the treble clef involves a lot
1644 of quote @code{'} marks. Consider this fragment from Mozart:
1646 @lilypond[verbatim,quote,ragged-right]
1650 cis''8. d''16 cis''8 e''4 e''8
1651 b'8. cis''16 b'8 d''4 d''8
1655 All these quotes makes the input less readable and they are a source
1656 of errors. With @code{\relative}, the previous example is much
1657 easier to read and type:
1659 @lilypond[verbatim,quote,ragged-right]
1663 cis8. d16 cis8 e4 e8
1668 If you make a mistake with an octave mark (@code{'} or @code{,})
1669 while working in @code{\relative} mode, it is very obvious -- many
1670 notes will be in the wrong octave. When working in absolute mode,
1671 a single mistake will not be as visible, and will not be as easy
1674 However, absolute mode is useful for music which has large
1675 intervals, and is extremely useful for computer-generated LilyPond
1680 @node After the tutorial
1681 @subsection After the tutorial
1683 FIXME: rewrite slightly after the rest of the LM has been
1684 stabilized. Translators, ignore this section for now.
1686 After finishing the tutorial, you should probably try writing a
1687 piece or two. Start by adding notes to one of the
1688 @ref{Templates}. If you need any notation that was not covered in
1689 the tutorial, look at the Notation Reference, starting with
1690 @ruser{Musical notation}. If you want to write for an instrument
1691 ensemble that is not covered in the templates, take a look at
1692 @ref{Extending the templates}.
1694 Once you have written a few short pieces, read the rest of the
1695 Learning Manual (chapters 3-5). There's nothing wrong with
1696 reading it now, of course! However, the rest of the Learning
1697 Manual assumes that you are familiar with LilyPond input. You may
1698 wish to skim these chapters right now, and come back to them after
1699 you have more experience.